rangler 0.1.0__py3-none-any.whl

rangler/__init__.py

@@ -0,0 +1,6 @@
+"""rangler: a macOS home-directory backup tool built on rclone.
+
+Author: John Grimes.
+"""
+
+__version__ = "0.1.0"

rangler/__main__.py

@@ -0,0 +1,9 @@
+"""Entry point for ``python -m rangler``.
+
+Author: John Grimes.
+"""
+
+from rangler.cli import cli
+
+if __name__ == "__main__":
+    cli()

rangler/backup.py

@@ -0,0 +1,327 @@
+"""Orchestrate a backup run over resolved targets.
+
+The pure core - :func:`execute_target` and :func:`run_targets` - runs each target
+through an injected rclone runner and aggregates :class:`TargetResult` records
+into a :class:`RunResult`, continuing past per-target failures. The orchestration
+- :func:`perform_backup` - wires in the real runner, the single-run lock, a
+per-run log file, and the ``last-run.json`` record, confining side effects to one
+place. A missing source yields a ``skipped_missing`` result, never a failure.
+
+Author: John Grimes.
+"""
+
+import json
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+from datetime import UTC, datetime
+from pathlib import Path
+
+from rangler.config import Config
+from rangler.locking import run_lock
+from rangler.paths import current_host, run_timestamp
+from rangler.rclone import build_sync_argv, interpret_exit_code, parse_stats, run_rclone
+from rangler.runtimestate import log_path, state_dir, write_last_run
+from rangler.targets import BackupTarget, resolve_targets
+
+# Name of the run lock file under the state directory.
+LOCK_NAME = "rangler.lock"
+
+
+@dataclass(frozen=True)
+class TargetResult:
+    """The outcome of attempting one backup target.
+
+    :ivar target: the attempted target.
+    :ivar status: ``"succeeded"``, ``"skipped_missing"``, or ``"failed"``.
+    :ivar files: files transferred (from rclone stats).
+    :ivar bytes: bytes transferred.
+    :ivar exit_code: rclone exit code, or ``None`` when skipped.
+    :ivar message: human-readable detail (error text on failure).
+    """
+
+    target: BackupTarget
+    status: str
+    files: int
+    bytes: int
+    exit_code: int | None
+    message: str
+
+
+@dataclass(frozen=True)
+class RunResult:
+    """The aggregate outcome of a whole run.
+
+    :ivar started_at: ISO-8601 run start time.
+    :ivar finished_at: ISO-8601 run end time.
+    :ivar dry_run: whether this was a dry run.
+    :ivar results: per-target outcomes.
+    :ivar host: sanitised hostname segment used for destinations.
+    """
+
+    started_at: str
+    finished_at: str
+    dry_run: bool
+    results: tuple[TargetResult, ...]
+    host: str
+
+
+def _error_detail(lines: list[str]) -> str:
+    """Extract a concise, human-readable error detail from rclone output.
+
+    Prefers the ``msg`` of the last JSON log entry (rclone runs with
+    ``--use-json-log``), falling back to the last non-empty raw line so the
+    reported detail reads as a sentence rather than a JSON blob.
+
+    :param lines: captured output lines.
+    :returns: a concise error message, or a generic fallback.
+    """
+    for line in reversed(lines):
+        if not line.strip():
+            continue
+        try:
+            entry = json.loads(line)
+        except (json.JSONDecodeError, TypeError):
+            return line.strip()
+        if isinstance(entry, dict) and entry.get("msg"):
+            return str(entry["msg"])
+        return line.strip()
+    return "rclone reported a failure"
+
+
+def _is_file(path: Path) -> bool:
+    """Report whether a path is a regular file (following symlinks)."""
+    return Path(path).is_file()
+
+
+def execute_target(
+    target: BackupTarget,
+    *,
+    runner: Callable[..., tuple[int, list[str]]],
+    exists: Callable[[Path], bool],
+    excludes: tuple[str, ...],
+    dry_run: bool,
+    is_file: Callable[[Path], bool] = _is_file,
+    on_line: Callable[[str], None] | None = None,
+) -> TargetResult:
+    """Run a single target through rclone and classify the outcome.
+
+    :param target: the target to back up.
+    :param runner: callable ``(argv, on_line=...) -> (exit_code, lines)``.
+    :param exists: predicate reporting whether the source path exists.
+    :param excludes: rclone filter patterns to apply.
+    :param dry_run: when true, rclone makes no changes.
+    :param is_file: predicate reporting whether the source is a single file.
+    :param on_line: optional sink for each rclone output line.
+    :returns: the :class:`TargetResult` for this target.
+    """
+    if not exists(target.source):
+        return TargetResult(
+            target=target,
+            status="skipped_missing",
+            files=0,
+            bytes=0,
+            exit_code=None,
+            message="source does not exist on this machine",
+        )
+
+    argv = build_sync_argv(
+        target, excludes, dry_run=dry_run, source_is_file=is_file(target.source)
+    )
+    code, lines = runner(argv, on_line=on_line)
+    stats = parse_stats(lines)
+    status = interpret_exit_code(code)
+    return TargetResult(
+        target=target,
+        status=status,
+        files=stats.transfers,
+        bytes=stats.bytes,
+        exit_code=code,
+        message="" if status == "succeeded" else _error_detail(lines),
+    )
+
+
+def run_targets(
+    targets: tuple[BackupTarget, ...],
+    *,
+    runner: Callable[..., tuple[int, list[str]]],
+    exists: Callable[[Path], bool],
+    excludes: tuple[str, ...],
+    dry_run: bool,
+    started_at: str,
+    finished_at: str,
+    host: str,
+    is_file: Callable[[Path], bool] = _is_file,
+    on_start: Callable[[BackupTarget], None] | None = None,
+    on_finish: Callable[[TargetResult], None] | None = None,
+    on_line: Callable[[str], None] | None = None,
+) -> RunResult:
+    """Run every target in order, aggregating results and continuing on failure.
+
+    :param targets: the resolved targets to process.
+    :param runner: the rclone runner (see :func:`execute_target`).
+    :param exists: source-existence predicate.
+    :param excludes: rclone filter patterns to apply.
+    :param dry_run: whether this is a dry run.
+    :param started_at: ISO-8601 run start time.
+    :param finished_at: ISO-8601 run end time.
+    :param host: the hostname segment for the run.
+    :param is_file: predicate reporting whether a source is a single file.
+    :param on_start: optional callback invoked with each target before it runs.
+    :param on_finish: optional callback invoked with each target's result.
+    :param on_line: optional sink for each rclone output line.
+    :returns: the aggregated :class:`RunResult`.
+    """
+    results: list[TargetResult] = []
+    for target in targets:
+        if on_start is not None:
+            on_start(target)
+        result = execute_target(
+            target,
+            runner=runner,
+            exists=exists,
+            excludes=excludes,
+            dry_run=dry_run,
+            is_file=is_file,
+            on_line=on_line,
+        )
+        if on_finish is not None:
+            on_finish(result)
+        results.append(result)
+
+    return RunResult(
+        started_at=started_at,
+        finished_at=finished_at,
+        dry_run=dry_run,
+        results=tuple(results),
+        host=host,
+    )
+
+
+def compact_record(run: RunResult) -> dict:
+    """Build the compact ``last-run.json`` record for a completed run.
+
+    :param run: the aggregate run result.
+    :returns: a JSON-serialisable summary with counts and an ``ok`` verdict.
+    """
+    failed = sum(1 for r in run.results if r.status == "failed")
+    succeeded = sum(1 for r in run.results if r.status == "succeeded")
+    skipped = sum(1 for r in run.results if r.status == "skipped_missing")
+    return {
+        "started_at": run.started_at,
+        "finished_at": run.finished_at,
+        "dry_run": run.dry_run,
+        "ok": failed == 0,
+        "succeeded": succeeded,
+        "failed": failed,
+        "skipped": skipped,
+    }
+
+
+def perform_backup(
+    config: Config,
+    *,
+    home: Path | None = None,
+    dry_run: bool = False,
+    host: str | None = None,
+    now: datetime | None = None,
+    runner: Callable[..., tuple[int, list[str]]] | None = None,
+    exists: Callable[[Path], bool] | None = None,
+    discovered: tuple[Path, ...] = (),
+    echo: Callable[[str], None] | None = None,
+) -> RunResult:
+    """Perform a full backup run: lock, transfer, log, and record.
+
+    Acquires the single-run lock for the duration, resolves targets, runs each
+    through rclone while streaming progress to ``echo`` and a per-run log file,
+    writes ``last-run.json``, and returns the result.
+
+    :param config: the validated configuration.
+    :param home: home directory override; defaults to ``Path.home()``.
+    :param dry_run: when true, rclone makes no changes to the remote.
+    :param host: hostname segment override; defaults to the system hostname.
+    :param now: run start time override; defaults to the current UTC time.
+    :param runner: rclone runner override; defaults to the real subprocess.
+    :param exists: source-existence predicate; defaults to ``Path.exists``.
+    :param discovered: discovered ``.local`` directories to include.
+    :param echo: optional sink for progress lines (e.g. stderr).
+    :returns: the aggregated :class:`RunResult`.
+    :raises LockHeld: if another run already holds the lock.
+    """
+    resolved_home = home if home is not None else Path.home()
+    start_time = now if now is not None else datetime.now(UTC)
+    resolved_host = host if host is not None else current_host()
+    emit = echo if echo is not None else (lambda _: None)
+    source_exists = exists if exists is not None else (lambda p: Path(p).exists())
+    actual_runner = (
+        runner
+        if runner is not None
+        else (lambda argv, on_line=None: run_rclone(argv, on_line=on_line))
+    )
+
+    timestamp = run_timestamp(start_time)
+    targets = resolve_targets(
+        config, resolved_host, resolved_home, timestamp, discovered=discovered
+    )
+
+    logfile = log_path(start_time, resolved_home)
+    logfile.parent.mkdir(parents=True, exist_ok=True)
+    lock = state_dir(resolved_home) / LOCK_NAME
+
+    with run_lock(lock), logfile.open("w", encoding="utf-8") as log:
+
+        def write_log(text: str) -> None:
+            log.write(text + "\n")
+
+        write_log(
+            f"rangler run start={start_time.isoformat()} host={resolved_host} "
+            f"dry_run={dry_run} targets={len(targets)}"
+        )
+
+        def on_start(target: BackupTarget) -> None:
+            line = f"[{target.kind}] {target.source} -> {target.dest}"
+            emit(line)
+            write_log(line)
+
+        def on_finish(result: TargetResult) -> None:
+            line = f"  {result.status}: {result.files} files, {result.bytes} bytes" + (
+                f" - {result.message}" if result.message else ""
+            )
+            emit(line)
+            write_log(line)
+
+        run = run_targets(
+            targets,
+            runner=actual_runner,
+            exists=source_exists,
+            excludes=config.excludes,
+            dry_run=dry_run,
+            started_at=start_time.isoformat(),
+            finished_at=start_time.isoformat(),
+            host=resolved_host,
+            on_start=on_start,
+            on_finish=on_finish,
+            on_line=write_log,
+        )
+        # Stamp the true end time now that all transfers have completed.
+        run = replace(run, finished_at=datetime.now(UTC).isoformat())
+        write_log(f"rangler run finished_at={run.finished_at}")
+
+    write_last_run(compact_record(run), resolved_home)
+    return run
+
+
+def note_skipped(home: Path | None = None, now: datetime | None = None) -> Path:
+    """Record that a run was skipped because the lock was already held.
+
+    :param home: home directory override; defaults to ``Path.home()``.
+    :param now: time override; defaults to the current UTC time.
+    :returns: the path of the skip log written.
+    """
+    moment = now if now is not None else datetime.now(UTC)
+    path = log_path(moment, home)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        f"rangler run skipped at {moment.isoformat()}: another run is in progress.\n",
+        encoding="utf-8",
+    )
+    return path

rangler/cli.py

@@ -0,0 +1,250 @@
+"""Click command-line interface for rangler.
+
+This is the thin orchestration layer: each command loads and validates
+configuration, composes the pure logic modules, and confines side effects to the
+subprocess and filesystem wrappers. Errors and progress go to stderr; primary
+output goes to stdout. Exit codes follow ``contracts/cli.md``.
+
+Author: John Grimes.
+"""
+
+import warnings
+from datetime import UTC, datetime
+from pathlib import Path
+
+import click
+
+from rangler import notify as notify_mod
+from rangler import rclone
+from rangler import schedule as schedule_mod
+from rangler.backup import note_skipped, perform_backup
+from rangler.config import (
+    Config,
+    ConfigError,
+    config_path,
+    load_config,
+    starter_template,
+)
+from rangler.discovery import discover_locals, list_subdirs
+from rangler.locking import LockHeld
+from rangler.paths import current_host, run_timestamp
+from rangler.runtimestate import describe_last_run, log_dir, read_last_run
+from rangler.summary import exit_code, render_summary
+from rangler.targets import resolve_targets
+
+
+def _fail(message: str, code: int) -> None:
+    """Print an actionable error to stderr and exit with the given code.
+
+    :param message: the human-readable error and remediation.
+    :param code: the process exit code to raise.
+    :raises SystemExit: always, with ``code``.
+    """
+    click.echo(f"Error: {message}", err=True)
+    raise SystemExit(code)
+
+
+def _load_or_exit() -> Config:
+    """Load and validate configuration, exiting 2 on any configuration error.
+
+    Unknown-key warnings are surfaced to stderr (typo protection) without
+    aborting.
+
+    :returns: the validated :class:`Config`.
+    :raises SystemExit: with code 2 if the configuration is missing or invalid.
+    """
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        try:
+            config = load_config()
+        except ConfigError as error:
+            _fail(str(error), 2)
+    for warning in caught:
+        click.echo(f"Warning: {warning.message}", err=True)
+    return config
+
+
+def _require_rclone(config: Config) -> None:
+    """Verify rclone is present and the remote is reachable, or exit 3.
+
+    :param config: the validated configuration.
+    :raises SystemExit: with code 3 if rclone is missing or unreachable.
+    """
+    if not rclone.rclone_available():
+        _fail(
+            "rclone is not installed or not on your PATH. Install it with "
+            "`brew install rclone`.",
+            3,
+        )
+    if not rclone.remote_reachable(config.remote_base):
+        _fail(
+            f"the remote {config.remote_base!r} is not reachable. Configure it "
+            f"with `rclone config` and check the name in remote_base.",
+            3,
+        )
+
+
+def _discover(config: Config, home: Path) -> tuple[Path, ...]:
+    """Discover project ``.local`` directories for the configured scan roots.
+
+    :param config: the validated configuration.
+    :param home: the home directory the scan roots are relative to.
+    :returns: the discovered ``.local`` directories.
+    """
+    return discover_locals(
+        config.scan_roots,
+        home,
+        config.max_depth,
+        config.excludes,
+        list_subdirs,
+    )
+
+
+@click.group()
+@click.version_option(package_name="rangler")
+def cli() -> None:
+    """Back up a macOS home directory to an rclone remote."""
+
+
+@cli.command()
+@click.option("--force", is_flag=True, help="Overwrite an existing config file.")
+def init(force: bool) -> None:
+    """Scaffold a starter config.toml when none exists."""
+    path = config_path()
+    if path.exists() and not force:
+        click.echo(f"Configuration already exists at {path}; nothing to do.")
+        return
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(starter_template(), encoding="utf-8")
+    except OSError as error:
+        _fail(f"could not write {path}: {error}", 1)
+    click.echo(
+        f"Wrote starter configuration to {path}.\n"
+        f"Edit it to set your remote and paths, then run `rangler check`."
+    )
+
+
+@cli.command()
+def check() -> None:
+    """Validate configuration and environment; preview the resolved targets."""
+    config = _load_or_exit()
+    _require_rclone(config)
+
+    home = Path.home()
+    host = current_host()
+    timestamp = run_timestamp(datetime.now(UTC))
+    discovered = _discover(config, home)
+    targets = resolve_targets(config, host, home, timestamp, discovered=discovered)
+
+    click.echo(
+        f"Configuration OK. rclone present and remote reachable. Host segment: {host}."
+    )
+    click.echo(f"{len(targets)} target(s):")
+    for target in targets:
+        click.echo(f"  [{target.kind}] {target.source} -> {target.dest}")
+
+
+@cli.command()
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Report intended changes without writing to the remote.",
+)
+def run(dry_run: bool) -> None:
+    """Back up all resolved targets, writing a log and a summary."""
+    config = _load_or_exit()
+    _require_rclone(config)
+
+    discovered = _discover(config, Path.home())
+    try:
+        result = perform_backup(
+            config,
+            dry_run=dry_run,
+            discovered=discovered,
+            echo=lambda line: click.echo(line, err=True),
+        )
+    except LockHeld:
+        note_skipped()
+        click.echo("skipped: already running", err=True)
+        return
+
+    click.echo(render_summary(result))
+    # Notify per policy at run completion. Scheduled runs reach this same path,
+    # since launchd invokes `rangler run`. Dry runs are previews and stay silent.
+    if not dry_run:
+        notify_mod.notify(result, config.notify)
+    code = exit_code(result)
+    if code != 0:
+        raise SystemExit(code)
+
+
+@cli.command()
+@click.option(
+    "--every",
+    default=None,
+    help="Interval such as 30m, 6h, or 1d; defaults to the config interval.",
+)
+def schedule(every: str | None) -> None:
+    """Install and load the scheduled backup LaunchAgent."""
+    config = _load_or_exit()
+    interval = every if every is not None else config.interval
+    try:
+        seconds = schedule_mod.parse_duration(interval)
+    except ValueError as error:
+        _fail(str(error), 2)
+
+    logs = log_dir()
+    logs.mkdir(parents=True, exist_ok=True)
+    plist = schedule_mod.build_plist(
+        schedule_mod.default_program_args(),
+        seconds,
+        str(logs / "launchd.out.log"),
+        str(logs / "launchd.err.log"),
+    )
+    path = schedule_mod.plist_path()
+    schedule_mod.write_plist(path, plist)
+
+    # Replace any previously loaded agent so re-scheduling is idempotent.
+    if schedule_mod.loaded():
+        schedule_mod.bootout()
+    result = schedule_mod.bootstrap(path)
+    if result.returncode != 0:
+        _fail(
+            f"launchctl could not load the agent: "
+            f"{result.stderr.strip() or result.returncode}",
+            1,
+        )
+
+    click.echo(
+        f"Scheduled rangler to run every {interval}. "
+        f"LaunchAgent {schedule_mod.LABEL} is loaded."
+    )
+
+
+@cli.command()
+def unschedule() -> None:
+    """Unload and remove the scheduled backup LaunchAgent."""
+    # Best-effort unload: a not-loaded agent is not an error (idempotent).
+    schedule_mod.bootout()
+    path = schedule_mod.plist_path()
+    try:
+        if path.exists():
+            path.unlink()
+    except OSError as error:
+        _fail(f"could not remove {path}: {error}", 1)
+    click.echo(f"Unscheduled rangler. LaunchAgent {schedule_mod.LABEL} removed.")
+
+
+@cli.command()
+def status() -> None:
+    """Report schedule state and the last run's outcome."""
+    state = schedule_mod.query_schedule()
+    if state.enabled:
+        click.echo(
+            f"Schedule: active, running every {state.interval} "
+            f"(LaunchAgent {state.label})."
+        )
+    else:
+        click.echo("Schedule: inactive.")
+    click.echo(f"Last run: {describe_last_run(read_last_run())}.")