sharefetch 1.0.0__py3-none-any.whl

sharefetch/cli.py

@@ -0,0 +1,782 @@
+"""Command-line front end.
+
+The one place the operator's words become a :class:`~sharefetch.config.Settings`
+and a run's events become lines on a terminal. Every bound this module enforces
+is a validator in :mod:`sharefetch.config`, so the command-line front end and
+the graphical front end cannot disagree about what an option accepts.
+
+Two departures from the obvious construction, both deliberate:
+
+``Engine`` in place of ``engine.run``
+    ``engine.run`` is a three-line convenience that builds an
+    :class:`~sharefetch.engine.Engine` and calls its ``run``, and it returns no
+    handle on the instance. Ctrl+C has to reach ``Engine.stop``, which is the
+    method that lets the files in flight finish their chunk, flushes the state
+    file and writes the manifest, so this module builds the engine itself and
+    keeps the reference. ``engine_factory`` is the seam a test replaces.
+
+``_check_log_file``
+    Every other boundary check is a ``config`` validator. ``--log-file`` has no
+    counterpart in the graphical interface, so its
+    check lives here and no second front end can diverge from it.
+
+``print`` appears twice by design and nowhere else: the ``--dry-run`` listing
+and the version banner argparse writes. Every other word this module puts in
+front of an operator goes through the logger, which carries the redaction
+filter.
+"""
+
+import argparse
+import logging
+import signal
+import sys
+import types
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+from . import __version__
+from .config import (
+    CHUNK_KIB_BOUNDS,
+    CONNECTIONS_BOUNDS,
+    DEFAULT_CHUNK_KIB,
+    DEFAULT_CLIENT_ID,
+    DEFAULT_CONNECTIONS,
+    DEFAULT_DELAY_SECONDS,
+    DEFAULT_TENANT,
+    DELAY_BOUNDS,
+    LIMIT_RATE_MIN_KBPS,
+    MIN_DEPTH,
+    Settings,
+    check_chunk_kib,
+    check_client_id,
+    check_connections,
+    check_delay,
+    check_dest,
+    check_limit_rate,
+    check_max_depth,
+    check_tenant,
+)
+from .engine import Engine
+from .errors import SharefetchError, ValidationError
+from .events import (
+    DeviceCodeCompleted,
+    DeviceCodeRequested,
+    EnumerationComplete,
+    EnumerationProgress,
+    Event,
+    FileFinished,
+    FileProgress,
+    FileStarted,
+    LogRecord,
+    Reconciled,
+    Resolved,
+    RunFinished,
+    RunSummary,
+    Throttled,
+)
+from .graph import RedactingFilter
+from .paths import sanitise_segment
+from .state import StateStore
+from .urls import SUPPORTED_FORMS, ShareRef, SourceRef
+from .urls import parse as parse_url
+
+logger = logging.getLogger(__name__)
+
+PROGRAM_NAME = "sharefetch"
+
+# A skipped item exits 1 alongside a failed one,
+# because the run did not transfer everything it was asked for even though
+# nothing malfunctioned.
+EXIT_OK = 0
+EXIT_INCOMPLETE = 1
+EXIT_FATAL = 2
+EXIT_INTERRUPTED = 130
+
+LOG_FORMAT = "%(asctime)s %(levelname)-8s %(name)s %(message)s"
+LOG_DATE_FORMAT = "%Y-%m-%dT%H:%M:%S"
+
+# Column widths for the --dry-run listing. The status column fits the longest
+# member of config.ITEM_STATUSES and the byte column fits a terabyte written
+# with thousands separators.
+_STATUS_COLUMN = 9
+_BYTES_COLUMN = 15
+
+_LOG_LEVELS = frozenset({"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"})
+
+
+# ----------------------------------------------------------------------
+# Parsing
+# ----------------------------------------------------------------------
+
+
+class _Parser(argparse.ArgumentParser):
+    """An ``ArgumentParser`` whose refusals are ``ValidationError``.
+
+    argparse's own ``error`` writes to stderr and raises ``SystemExit``, which
+    would put operator output outside the logger and outside the redaction
+    filter. Raising instead routes an unknown option, a missing argument, a
+    mutually exclusive pair and a rejected value through the one path
+    :func:`main` already has for a fatal setup failure. ``--help`` and
+    ``--version`` go through ``exit`` rather than ``error`` and keep their
+    ``SystemExit``.
+    """
+
+    def error(self, message: str) -> Any:
+        raise ValidationError(message)
+
+
+def _bounded_int(name: str, check: Callable[[int], Any]) -> Callable[[str], int]:
+    """Return an argparse ``type`` that parses an integer and applies ``check``."""
+
+    def convert(value: str) -> int:
+        try:
+            number = int(value)
+        except ValueError:
+            raise argparse.ArgumentTypeError(
+                f"{name} must be an integer, received {value!r}"
+            ) from None
+        try:
+            check(number)
+        except ValidationError as exc:
+            raise argparse.ArgumentTypeError(str(exc)) from None
+        return number
+
+    return convert
+
+
+def _bounded_float(name: str, check: Callable[[float], Any]) -> Callable[[str], float]:
+    """Return an argparse ``type`` that parses a float and applies ``check``."""
+
+    def convert(value: str) -> float:
+        try:
+            number = float(value)
+        except ValueError:
+            raise argparse.ArgumentTypeError(
+                f"{name} must be a number, received {value!r}"
+            ) from None
+        try:
+            check(number)
+        except ValidationError as exc:
+            raise argparse.ArgumentTypeError(str(exc)) from None
+        return number
+
+    return convert
+
+
+def _checked_str(check: Callable[[str], str]) -> Callable[[str], str]:
+    """Return an argparse ``type`` that applies a ``config`` string validator."""
+
+    def convert(value: str) -> str:
+        try:
+            return check(value)
+        except ValidationError as exc:
+            raise argparse.ArgumentTypeError(str(exc)) from None
+
+    return convert
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the parser for the full option table."""
+    low_connections, high_connections = CONNECTIONS_BOUNDS
+    low_delay, high_delay = DELAY_BOUNDS
+    low_chunk, high_chunk = CHUNK_KIB_BOUNDS
+
+    parser = _Parser(
+        prog=PROGRAM_NAME,
+        description=(
+            "Download a SharePoint Online or OneDrive for Business folder tree "
+            "by Microsoft Graph, resumably and with content-level verification."
+        ),
+        epilog="supported URL forms:\n  " + "\n  ".join(SUPPORTED_FORMS),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument(
+        "url",
+        metavar="url",
+        help="the SharePoint or OneDrive URL naming the folder to download",
+    )
+    parser.add_argument(
+        "--dest",
+        metavar="DIR",
+        default=None,
+        help=(
+            "destination directory; defaults to a folder named after the "
+            "addressed folder, under the working directory"
+        ),
+    )
+    parser.add_argument(
+        "--connections",
+        metavar="N",
+        type=_bounded_int("connections", check_connections),
+        default=DEFAULT_CONNECTIONS,
+        help=(
+            f"number of concurrent transfers, {low_connections} or "
+            f"{high_connections} (default: {DEFAULT_CONNECTIONS})"
+        ),
+    )
+    parser.add_argument(
+        "--delay",
+        metavar="SECONDS",
+        type=_bounded_float("delay", check_delay),
+        default=DEFAULT_DELAY_SECONDS,
+        help=(
+            f"pause between requests, {low_delay} to {high_delay} seconds "
+            f"(default: {DEFAULT_DELAY_SECONDS})"
+        ),
+    )
+    parser.add_argument(
+        "--limit-rate",
+        metavar="KBPS",
+        dest="limit_rate_kbps",
+        type=_bounded_int("rate limit", check_limit_rate),
+        default=None,
+        help=(
+            f"ceiling on transfer rate in KB/s, at least {LIMIT_RATE_MIN_KBPS} "
+            "(default: no ceiling)"
+        ),
+    )
+    parser.add_argument(
+        "--chunk-size",
+        metavar="KIB",
+        dest="chunk_kib",
+        type=_bounded_int("chunk size in KiB", check_chunk_kib),
+        default=DEFAULT_CHUNK_KIB,
+        help=(f"read size in KiB, {low_chunk} to {high_chunk} (default: {DEFAULT_CHUNK_KIB})"),
+    )
+    parser.add_argument(
+        "--max-depth",
+        metavar="N",
+        type=_bounded_int("max depth", check_max_depth),
+        default=None,
+        help=(f"deepest folder level to walk, {MIN_DEPTH} or above (default: unlimited)"),
+    )
+    parser.add_argument(
+        "--include",
+        metavar="GLOB",
+        action="append",
+        default=[],
+        help="only transfer items matching this glob; repeatable",
+    )
+    parser.add_argument(
+        "--exclude",
+        metavar="GLOB",
+        action="append",
+        default=[],
+        help="skip items matching this glob, applied after --include; repeatable",
+    )
+
+    restart_group = parser.add_mutually_exclusive_group()
+    restart_group.add_argument(
+        "--resume",
+        dest="restart",
+        action="store_false",
+        help="continue a previous run from its state file (default)",
+    )
+    restart_group.add_argument(
+        "--restart",
+        dest="restart",
+        action="store_true",
+        help="ignore recorded progress and transfer every item again",
+    )
+    parser.set_defaults(restart=False)
+
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="enumerate, reconcile and report, writing state but no file content",
+    )
+    parser.add_argument(
+        "--verify-only",
+        action="store_true",
+        help="verify the tree already on disk, making no network call",
+    )
+    parser.add_argument(
+        "--reauth",
+        action="store_true",
+        help="ignore the cached refresh token and force a device code",
+    )
+    parser.add_argument(
+        "--tenant",
+        metavar="ID",
+        type=_checked_str(check_tenant),
+        default=DEFAULT_TENANT,
+        help=f"tenant GUID or domain (default: {DEFAULT_TENANT})",
+    )
+    parser.add_argument(
+        "--client-id",
+        metavar="GUID",
+        type=_checked_str(check_client_id),
+        default=DEFAULT_CLIENT_ID,
+        help=f"application GUID to sign in with (default: {DEFAULT_CLIENT_ID})",
+    )
+    parser.add_argument(
+        "--ignore-free-space",
+        action="store_true",
+        help="skip the pre-flight capacity check",
+    )
+    parser.add_argument(
+        "--log-file",
+        metavar="PATH",
+        default=None,
+        help="write the log to this file as well as to stderr",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="log at DEBUG in place of INFO",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+        help="print the version and exit",
+    )
+    return parser
+
+
+def _default_dest(reference: SourceRef) -> Path:
+    """Return the destination a URL implies, under the working directory.
+
+    Raises:
+        ValidationError: the URL is a sharing link. A sharing link carries a
+            token and no folder name, and the name only becomes known once the
+            run resolves the link against the service, which is after the
+            destination has to exist. ``--dest`` is required in that case.
+    """
+    if isinstance(reference, ShareRef):
+        raise ValidationError(
+            "a sharing link names no folder until the run resolves it against "
+            "the service, and the destination has to be chosen before that, so "
+            "--dest must be given when the URL is a sharing link"
+        )
+    name, changed = sanitise_segment(reference.path_segments[-1])
+    if changed:
+        logger.info("the default destination folder name was sanitised to %r", name)
+    return Path.cwd() / name
+
+
+def _check_log_file(value: str | None) -> Path | None:
+    """Return the log file as an absolute path, rejecting an unusable parent."""
+    if value is None:
+        return None
+    if not str(value).strip():
+        raise ValidationError("log file must be a file path, received an empty value")
+    path = Path(value).expanduser().resolve()
+    if path.is_dir():
+        raise ValidationError(f"log file must be a file, received {path}, which is a directory")
+    if not path.parent.is_dir():
+        raise ValidationError(
+            f"log file parent directory must exist, received {path}, "
+            f"whose parent {path.parent} does not exist"
+        )
+    return path
+
+
+def parse_args(argv: list[str] | None = None) -> Settings:
+    """Turn a command line into validated ``Settings``.
+
+    Every numeric bound is applied by the parser's ``type`` callables, so a
+    value outside its range never reaches this function's body. The URL, the
+    destination and the log file are checked here, because each depends on more
+    than the one string argparse hands over.
+
+    Raises:
+        ValidationError: any option, the URL, the destination or the log file
+            failed its check. The message names the value received and the
+            range or rule that rejected it.
+        SystemExit: ``--help`` or ``--version`` was given.
+    """
+    args = build_parser().parse_args(argv)
+
+    reference = parse_url(args.url)
+    dest = check_dest(args.dest) if args.dest is not None else check_dest(_default_dest(reference))
+
+    return Settings(
+        url=args.url,
+        dest=dest,
+        connections=args.connections,
+        delay=args.delay,
+        limit_rate_kbps=args.limit_rate_kbps,
+        chunk_kib=args.chunk_kib,
+        max_depth=args.max_depth,
+        include=tuple(args.include),
+        exclude=tuple(args.exclude),
+        restart=args.restart,
+        dry_run=args.dry_run,
+        verify_only=args.verify_only,
+        reauth=args.reauth,
+        tenant=args.tenant,
+        client_id=args.client_id,
+        ignore_free_space=args.ignore_free_space,
+        log_file=_check_log_file(args.log_file),
+        verbose=args.verbose,
+    )
+
+
+# ----------------------------------------------------------------------
+# Logging
+# ----------------------------------------------------------------------
+
+
+# Marks a record that may reach the console and must not reach a log file. The
+# only record carrying it is the device-code instruction, which holds the user
+# code.
+CONSOLE_ONLY = "console_only"
+
+
+class _ConsoleOnlyFilter(logging.Filter):
+    """Drop records marked console-only, so a log file never holds a user code."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        return not getattr(record, CONSOLE_ONLY, False)
+
+
+def configure_logging(verbose: bool = False, log_file: Path | None = None) -> None:
+    """Install the handlers this front end logs through.
+
+    The library configures no handler and the front end configures them all.
+    Every handler installed here carries
+    :class:`~sharefetch.graph.RedactingFilter`, so a line written by this
+    package, by ``requests`` or by ``urllib3`` is masked alike.
+
+    Called twice in a normal run: once before parsing, so a rejected option has
+    somewhere to be reported, and once after, when ``--verbose`` and
+    ``--log-file`` are known. ``force`` makes the second call replace the first
+    call's handlers rather than doubling every line.
+    """
+    level = logging.DEBUG if verbose else logging.INFO
+    handlers: list[logging.Handler] = [logging.StreamHandler(sys.stderr)]
+    if log_file is not None:
+        file_handler = logging.FileHandler(log_file, encoding="utf-8")
+        file_handler.addFilter(_ConsoleOnlyFilter())
+        handlers.append(file_handler)
+
+    redaction = RedactingFilter()
+    for handler in handlers:
+        handler.addFilter(redaction)
+
+    logging.basicConfig(
+        level=level,
+        format=LOG_FORMAT,
+        datefmt=LOG_DATE_FORMAT,
+        handlers=handlers,
+        force=True,
+    )
+
+
+# ----------------------------------------------------------------------
+# The event sink
+# ----------------------------------------------------------------------
+
+
+class CliSink:
+    """Writes each run event through the logger.
+
+    Levels are fixed: DEBUG for per-chunk and per-request trace, INFO for
+    milestones, WARNING for a recoverable condition and ERROR for a failed
+    item.
+    """
+
+    def __init__(self) -> None:
+        self._handlers: dict[type, Callable[[Any], None]] = {
+            Resolved: self._on_resolved,
+            DeviceCodeRequested: self._on_device_code_requested,
+            DeviceCodeCompleted: self._on_device_code_completed,
+            EnumerationProgress: self._on_enumeration_progress,
+            EnumerationComplete: self._on_enumeration_complete,
+            Reconciled: self._on_reconciled,
+            FileStarted: self._on_file_started,
+            FileProgress: self._on_file_progress,
+            FileFinished: self._on_file_finished,
+            Throttled: self._on_throttled,
+            RunFinished: self._on_run_finished,
+            LogRecord: self._on_log_record,
+        }
+
+    def emit(self, event: Event) -> None:
+        handler = self._handlers.get(type(event))
+        if handler is None:
+            logger.debug("an event of type %s was emitted and has no sink line", type(event))
+            return
+        handler(event)
+
+    def _on_resolved(self, event: Resolved) -> None:
+        logger.info(
+            "resolved to the %s library at %s, folder %r, drive %s",
+            event.drive_name,
+            event.site_web_url,
+            event.folder_path,
+            event.drive_id,
+        )
+
+    def _on_device_code_requested(self, event: DeviceCodeRequested) -> None:
+        # The service composes ``message`` as the full instruction to the
+        # operator, including the code and the URI, and the server's own
+        # wording survives verbatim.
+        #
+        # The user code is phishing material: anyone holding it can poll the
+        # token endpoint and collect the token the moment the legitimate
+        # operator completes the sign-in. It has to reach the screen, and it
+        # must not reach a file that outlives the code's few minutes of
+        # validity, so the record is marked console-only and the file handler
+        # drops it. The expiry instant is logged on its own line, which carries
+        # no code and is safe to keep.
+        logger.info("%s", event.message, extra={CONSOLE_ONLY: True})
+        logger.info(
+            "a sign-in code was issued at %s, expiring at %s",
+            event.verification_uri,
+            event.expires_at,
+        )
+
+    def _on_device_code_completed(self, event: DeviceCodeCompleted) -> None:
+        logger.info("signed in as %s", event.account)
+
+    def _on_enumeration_progress(self, event: EnumerationProgress) -> None:
+        logger.debug(
+            "enumerated %d folder(s), %d file(s), %d byte(s) so far",
+            event.folders,
+            event.files,
+            event.total_bytes,
+        )
+
+    def _on_enumeration_complete(self, event: EnumerationComplete) -> None:
+        logger.info(
+            "enumeration complete: %d file(s) in %d folder(s), %d byte(s)",
+            event.files,
+            event.folders,
+            event.total_bytes,
+        )
+
+    def _on_reconciled(self, event: Reconciled) -> None:
+        counts = ", ".join(f"{status}={count}" for status, count in sorted(event.counts.items()))
+        logger.info("reconciled against the state file: %s", counts or "no items")
+
+    def _on_file_started(self, event: FileStarted) -> None:
+        if event.resume_from:
+            logger.info(
+                "%s: resuming at byte %d of %d", event.drive_path, event.resume_from, event.size
+            )
+        else:
+            logger.info("%s: starting, %d byte(s)", event.drive_path, event.size)
+
+    def _on_file_progress(self, event: FileProgress) -> None:
+        logger.debug(
+            "%s: %d of %d byte(s) written",
+            event.drive_path,
+            event.bytes_written,
+            event.size,
+        )
+
+    def _on_file_finished(self, event: FileFinished) -> None:
+        verification = getattr(event.verification, "status", None)
+        if event.error:
+            logger.error(
+                "%s: %s, verification %s, %s",
+                event.drive_path,
+                event.status,
+                verification or "not run",
+                event.error,
+            )
+            return
+        logger.info(
+            "%s: %s, verification %s",
+            event.drive_path,
+            event.status,
+            verification or "not run",
+        )
+
+    def _on_throttled(self, event: Throttled) -> None:
+        logger.warning("held for %.1f second(s): %s", event.seconds, event.reason)
+
+    def _on_run_finished(self, event: RunFinished) -> None:
+        summary = event.summary
+        logger.info(
+            "run finished: %d transferred, %d already present, %d skipped, %d failed, "
+            "%d verified, %d byte(s) transferred",
+            summary.transferred,
+            summary.already_present,
+            summary.skipped,
+            summary.failed,
+            summary.verified,
+            summary.bytes_transferred,
+        )
+        if summary.hash_algorithm_validated is False:
+            logger.warning(
+                "the hash implementation safeguard did not validate; content hashes "
+                "from this run carry no weight"
+            )
+        if event.manifest_path is None:
+            logger.info("no manifest was written")
+        else:
+            logger.info("manifest: %s", event.manifest_path)
+
+    def _on_log_record(self, event: LogRecord) -> None:
+        # Reaches this sink only where a caller attached the logging handler,
+        # which the command-line front end does not. Its level is a
+        # name from the record it came from, and an unknown one is carried at
+        # INFO rather than dropped.
+        name = (event.level or "").upper()
+        level = logging.getLevelName(name) if name in _LOG_LEVELS else logging.INFO
+        logger.log(level, "%s", event.message)
+
+
+# ----------------------------------------------------------------------
+# Running
+# ----------------------------------------------------------------------
+
+
+@runtime_checkable
+class EngineLike(Protocol):
+    """The part of :class:`~sharefetch.engine.Engine` this front end drives."""
+
+    def run(self) -> RunSummary: ...
+
+    def stop(self) -> None: ...
+
+
+class _InterruptGuard:
+    """Turns the operator's first Ctrl+C into ``Engine.stop``.
+
+    Letting ``KeyboardInterrupt`` unwind out of a run cuts the file in flight at
+    whatever byte the read had reached and skips the manifest. ``stop`` instead
+    ends the queue at the next chunk boundary, flushes the state file and lets
+    the run return its summary, which is what Stop means and what leaves the
+    least work for the next run to redo.
+
+    The previous handler is restored the moment the first signal arrives, so a
+    second Ctrl+C from an operator who has waited long enough aborts the process
+    the usual way.
+
+    A handler can only be installed from the main thread. Where it cannot be,
+    the guard records the reason and :func:`main` falls back to catching
+    ``KeyboardInterrupt``, which is the behaviour without the guard at all.
+    """
+
+    def __init__(self, engine: EngineLike) -> None:
+        self._engine = engine
+        self._previous: Any = None
+        self._installed = False
+        self.fired = False
+
+    def _handle(self, signum: int, frame: types.FrameType | None) -> None:  # noqa: ARG002
+        self.fired = True
+        if self._previous is not None:
+            signal.signal(signal.SIGINT, self._previous)
+            self._installed = False
+        logger.warning(
+            "interrupt received: finishing the file(s) in flight and flushing state; "
+            "interrupt again to abort immediately"
+        )
+        self._engine.stop()
+
+    def __enter__(self) -> "_InterruptGuard":
+        try:
+            self._previous = signal.signal(signal.SIGINT, self._handle)
+        except ValueError as exc:
+            # signal.signal outside the main thread. Documented, not silent.
+            logger.debug("no interrupt handler was installed: %s", exc)
+            return self
+        self._installed = True
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:
+        if self._installed and self._previous is not None:
+            signal.signal(signal.SIGINT, self._previous)
+            self._installed = False
+        return False
+
+
+def _print_dry_run_listing(dest: Path) -> None:
+    """Print what a dry run enumerated, read back from the state file it wrote.
+
+    One of the two places this package prints. The listing is operator output
+    on stdout rather than a log line, so it can be piped into a file while the
+    log stays on stderr.
+    """
+    store = StateStore.load(dest)
+    if store is None:
+        logger.warning(
+            "no readable state file was written under %s, so no dry-run listing can be printed",
+            dest,
+        )
+        return
+
+    items = store.all_items()
+    print(f"{len(items)} item(s) enumerated into {dest}")
+    total = 0
+    for drive_path in sorted(items):
+        item = items[drive_path]
+        total += item.size
+        print(f"  {item.status:<{_STATUS_COLUMN}} {item.size:>{_BYTES_COLUMN},} {drive_path}")
+    print(f"  {'total':<{_STATUS_COLUMN}} {total:>{_BYTES_COLUMN},} bytes")
+
+
+def _exit_code(summary: RunSummary) -> int:
+    """Map a summary onto exit code 0 or 1.
+
+    A skipped item exits 1 alongside a failed one. Nothing malfunctioned, and
+    the run still did not bring down everything it was asked for.
+    """
+    if summary.failed or summary.skipped:
+        logger.warning(
+            "the run finished with %d failed and %d skipped item(s)",
+            summary.failed,
+            summary.skipped,
+        )
+        return EXIT_INCOMPLETE
+    return EXIT_OK
+
+
+def main(
+    argv: list[str] | None = None, *, engine_factory: Callable[..., EngineLike] = Engine
+) -> int:
+    """Run one command line and return its exit code.
+
+    ``engine_factory`` is called with the settings and the sink and defaults to
+    :class:`~sharefetch.engine.Engine`. A test replaces it to drive every exit
+    code without a socket, a sign-in or an elapsed clock.
+
+    Returns one of four codes: ``0`` where
+    every item is complete and verified, ``1`` where the run finished with a
+    failed or skipped item, ``2`` for a fatal condition before or during setup,
+    and ``130`` where the operator interrupted it.
+    """
+    configure_logging()
+
+    try:
+        settings = parse_args(argv)
+    except SystemExit as exc:
+        # --help and --version. argparse has already written its output.
+        return int(exc.code or 0)
+    except SharefetchError as exc:
+        logger.error("%s", exc)
+        return EXIT_FATAL
+
+    configure_logging(verbose=settings.verbose, log_file=settings.log_file)
+    logger.debug("destination %s", settings.dest)
+
+    engine = engine_factory(settings, CliSink())
+    guard = _InterruptGuard(engine)
+
+    try:
+        with guard:
+            summary = engine.run()
+    except KeyboardInterrupt:
+        # Reached where no handler was installed, or on the second interrupt.
+        engine.stop()
+        logger.warning("interrupted by the operator; progress on disk stays resumable")
+        return EXIT_INTERRUPTED
+    except SharefetchError as exc:
+        logger.error("%s", exc)
+        return EXIT_FATAL
+
+    if settings.dry_run:
+        _print_dry_run_listing(settings.dest)
+
+    if guard.fired:
+        logger.warning("interrupted by the operator; progress on disk stays resumable")
+        return EXIT_INTERRUPTED
+
+    return _exit_code(summary)