#!/usr/bin/env python3
"""omniopt_share - Share OmniOpt runs with a unified JSON/ZIP protocol.

Python rewrite of the former ``omniopt_share`` bash script, with a new
on-the-wire format:

  ``manifest.json``     - JSON document describing every file in the share.
  ``bundle.zip``        - ZIP archive with all the actual file contents.

The GUI server (``share_internal.php``) accepts these two as
``multipart/form-data`` parts named ``manifest`` and ``bundle``.  Because
every file is enumerated in the manifest, the server can:

  * verify each file's SHA-256 against the value declared in the manifest
  * reject any file whose ``archive_path`` would escape the share root
  * reject any file larger than a server-configured limit
  * apply its own whitelist independently of the client
  * add support for new file types purely by editing the manifest schema

CLI flags are 100 % backwards-compatible with the bash version.

Behavioural compatibility:
  * ``--update`` sends only files changed since the last successful share
    (cache in ``~/.oo_share_cache``); ``--force`` re-sends everything
  * large ``state_files/`` snapshots are skipped unless
    ``--include_state_files`` is given
  * ``--debug`` / ``--no_color`` / ``--timeout``
  * ``--username`` / ``--password`` / ``--outfile`` / ``--dont_send_singleruns``
  * Run dirs must contain ``results.csv`` (validated server-side)
  * Default ``BASEURL`` is the same as before, overridable via
    ``$HOME/.oo_base_url``
"""

from __future__ import annotations

import argparse
import datetime
import hashlib
import json
import os
import re
import shutil
import sys
import tempfile
import time
import urllib.error
import urllib.request
import zipfile
from pathlib import Path
from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Tuple


SCRIPT_DIR = Path(__file__).resolve().parent

MANIFEST_SCHEMA_VERSION = "1.0"

# Server-imposed upper bound on the size of any single shared file
# (1 GiB).  The PHP side enforces the same value.
MAX_FILE_SIZE = 1 << 30

DEFAULT_BASE_URL = "https://imageseg.scads.de/omniax"

# Whitelisted file extensions for the top-level of a run dir.
TOP_LEVEL_EXTENSIONS = (".csv", ".txt", ".log", ".json")

# Whitelisted file extensions under state_files/.
STATE_FILE_EXTENSIONS = (".csv", ".txt", ".json")

# Sub-extension patterns used for single_run files (e.g. 0.out, 0.err).
SINGLE_RUN_SUFFIXES = (".out", ".err")

# Files above this size are stored uncompressed in the bundle.  They are
# usually snapshots (json/csv) where deflate costs a lot of CPU but saves
# comparatively little.  Small text files are still compressed.
COMPRESS_MAX_SIZE = 4 * 1024 * 1024

# How long a single HTTP operation may block (seconds).  Large uploads can
# take a while, but should never hang forever.
DEFAULT_POST_TIMEOUT = 300

# Local cache of hashes from the last successful share.  Used to upload only
# changed files on ``--update`` instead of re-zipping/re-sending everything.
CACHE_VERSION = 1
CACHE_MAX_AGE_SECONDS = 30 * 24 * 60 * 60

USERNAME_FILE = Path.home() / ".oo_share_username"
DONT_ASK_FILE = Path.home() / ".oo_share_dont_ask"
BASE_URL_FILE = Path.home() / ".oo_base_url"


# ---------------------------------------------------------------------------
# Validation helpers
# ---------------------------------------------------------------------------


def is_valid_username(name: str) -> bool:
    """Reject empty / whitespace-containing usernames."""
    return bool(name) and not any(c.isspace() for c in name)


def sanitize_archive_path(path: str) -> str:
    """Reject paths that try to escape the archive root.

    Accepted forms: ``results.csv`` or ``state_files/run_uuid``.
    Rejected: absolute paths, ``..`` traversal, null bytes, backslashes.
    """
    if not path or path != path.strip():
        raise ValueError(f"Invalid archive_path: {path!r}")
    if "\x00" in path:
        raise ValueError(f"Null byte in archive_path: {path!r}")
    if "\\" in path or path.startswith("/"):
        raise ValueError(f"Absolute or backslash path rejected: {path!r}")
    parts = path.split("/")
    if any(p in ("", ".", "..") for p in parts):
        raise ValueError(f"Unsafe path component in {path!r}")
    return path


# ---------------------------------------------------------------------------
# File discovery
# ---------------------------------------------------------------------------


def collect_shareable_files(
    run_dir: str,
    send_single_runs: bool = True,
    include_state_files: bool = True,
) -> List[Dict[str, Any]]:
    """Walk ``run_dir`` and return the list of shareable files.

    Each entry is a dict with at least:

        ``local_path``   - absolute Path on disk
        ``archive_path`` - path inside the zip (always safe per
                           :func:`sanitize_archive_path`)
        ``name``         - logical name (filename without extension,
                           matching the legacy ``-F key=@file`` mapping)

    Extension / directory rules match the legacy bash version.
    ``include_state_files=False`` keeps only ``state_files/run_uuid`` (which
    the server needs to match updates) and skips large snapshots such as
    ``pd.json``/``checkpoint.json`` that the GUI does not read.
    """
    root = Path(run_dir)
    if not root.is_dir():
        return []

    out: List[Dict[str, Any]] = []

    # Top-level files
    for entry in sorted(root.iterdir()):
        if entry.is_file() and entry.suffix.lower() in TOP_LEVEL_EXTENSIONS:
            name = entry.stem
            out.append(
                {
                    "name": name,
                    "archive_path": sanitize_archive_path(entry.name),
                    "local_path": entry,
                }
            )

    # git_version (no specific extension requirement)
    git_version = root / "git_version"
    if git_version.is_file():
        out.append(
            {
                "name": "git_version",
                "archive_path": "git_version",
                "local_path": git_version,
            }
        )

    # state_files/ - only csv/txt/json.  Large checkpoint/model snapshots are
    # skipped by default; the GUI only needs run_uuid (added separately).
    sf = root / "state_files"
    if sf.is_dir() and include_state_files:
        for entry in sorted(sf.iterdir()):
            if entry.is_file() and entry.suffix.lower() in STATE_FILE_EXTENSIONS:
                out.append(
                    {
                        "name": entry.stem,
                        "archive_path": sanitize_archive_path(
                            f"state_files/{entry.name}"
                        ),
                        "local_path": entry,
                    }
                )

    # state_files/run_uuid (no extension — always include for update matching)
    run_uuid_file = root / "state_files" / "run_uuid"
    if run_uuid_file.is_file():
        out.append(
            {
                "name": "run_uuid",
                "archive_path": "state_files/run_uuid",
                "local_path": run_uuid_file,
            }
        )

    # single_runs/<digit>/<file.{out,err}>  (optional)
    if send_single_runs:
        sr = root / "single_runs"
        if sr.is_dir():
            for run_folder in sorted(sr.iterdir()):
                if not run_folder.is_dir() or not run_folder.name.isdigit():
                    continue
                for entry in sorted(run_folder.iterdir()):
                    if (
                        entry.is_file()
                        and entry.suffix.lower() in SINGLE_RUN_SUFFIXES
                    ):
                        out.append(
                            {
                                "name": f"single_run_file_{run_folder.name}_{entry.name}",
                                "archive_path": sanitize_archive_path(
                                    f"single_runs/{run_folder.name}/{entry.name}"
                                ),
                                "local_path": entry,
                            }
                        )

    return out


# ---------------------------------------------------------------------------
# Manifest assembly & validation
# ---------------------------------------------------------------------------


def _sha256_of(path: Path) -> str:
    h = hashlib.sha256()
    with path.open("rb") as f:
        for chunk in iter(lambda: f.read(1 << 20), b""):
            h.update(chunk)
    return h.hexdigest()


def build_manifest(
    *,
    run_dir: str,
    user_id: str,
    experiment_name: str,
    update: bool,
    update_uuid: Optional[str],
    password: Optional[str],
    send_single_runs: bool = True,
    include_state_files: bool = True,
    files: Optional[List[Dict[str, Any]]] = None,
) -> Dict[str, Any]:
    """Build a complete share manifest for ``run_dir``.

    ``files`` may be a pre-filtered subset (used for incremental updates).
    """
    if not is_valid_username(user_id):
        raise ValueError(f"Invalid username: {user_id!r}")

    if files is None:
        files = collect_shareable_files(
            run_dir,
            send_single_runs=send_single_runs,
            include_state_files=include_state_files,
        )
    entries: List[Dict[str, Any]] = []
    for f in files:
        local_path: Path = f["local_path"]
        size = local_path.stat().st_size
        if size > MAX_FILE_SIZE:
            raise ValueError(
                f"{local_path} is {size} bytes, larger than max {MAX_FILE_SIZE}"
            )
        entries.append(
            {
                "name": f["name"],
                "archive_path": f["archive_path"],
                "size": size,
                "sha256": _sha256_of(local_path),
                "content_type": _guess_content_type(local_path.name),
            }
        )

    # Always read the run_uuid if present — the server uses it to detect
    # whether this is a re-share of the same run (and updates in place).
    if update_uuid is None:
        run_uuid_path = Path(run_dir) / "state_files" / "run_uuid"
        if run_uuid_path.is_file():
            update_uuid = run_uuid_path.read_text(encoding="utf-8").strip()

    return {
        "schema_version": MANIFEST_SCHEMA_VERSION,
        "created_at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
        "client_version": "0.97",
        "user_id": user_id,
        "experiment_name": experiment_name,
        "update": bool(update),
        "update_uuid": update_uuid,
        "password": password,
        "files": entries,
    }


def _guess_content_type(name: str) -> str:
    ext = Path(name).suffix.lower()
    return {
        ".csv": "text/csv",
        ".json": "application/json",
        ".txt": "text/plain",
        ".log": "text/plain",
        ".out": "text/plain",
        ".err": "text/plain",
    }.get(ext, "application/octet-stream")


def verify_manifest(manifest: Dict[str, Any]) -> str:
    """Return ``""`` on success, error message otherwise.

    The PHP side runs an equivalent check.  This function exists so the
    Python client can dry-validate its own manifest before uploading.
    """
    required = (
        "schema_version",
        "user_id",
        "experiment_name",
        "update",
        "update_uuid",
        "password",
        "files",
    )
    for key in required:
        if key not in manifest:
            return f"Missing manifest key: {key!r}"

    if manifest["schema_version"] != MANIFEST_SCHEMA_VERSION:
        return (
            f"Unsupported manifest schema_version "
            f"{manifest['schema_version']!r}, expected "
            f"{MANIFEST_SCHEMA_VERSION!r}"
        )
    if not is_valid_username(str(manifest["user_id"])):
        return f"Invalid user_id: {manifest['user_id']!r}"
    # `update` must be a real bool, not just truthy.
    if not isinstance(manifest["update"], bool):
        return (
            f"update must be bool, got "
            f"{type(manifest['update']).__name__}: {manifest['update']!r}"
        )

    files = manifest["files"]
    if not isinstance(files, list):
        return "files must be a list"
    if len(files) == 0:
        return "Manifest has no files (nothing to share)"
    for f in files:
        try:
            sanitize_archive_path(str(f["archive_path"]))
        except (KeyError, ValueError) as e:
            return f"Bad archive_path: {e}"
        try:
            size = int(f["size"])
        except (KeyError, ValueError, TypeError):
            return f"Bad size: {f.get('size')!r}"
        if isinstance(f["size"], bool) or not isinstance(f["size"], int):
            return f"Size must be int, got {type(f['size']).__name__}: {f['size']!r}"
        if size < 0 or size > MAX_FILE_SIZE:
            return f"Size out of range: {size}"
        sha = f.get("sha256")
        if not isinstance(sha, str) or len(sha) != 64:
            return f"Bad sha256: {sha!r}"
    return ""


# ---------------------------------------------------------------------------
# Incremental-update cache
# ---------------------------------------------------------------------------


def _cache_dir() -> Path:
    return Path(
        os.environ.get("OO_SHARE_CACHE_DIR", str(Path.home() / ".oo_share_cache"))
    )


def _cache_file_path(
    run_dir: str,
    user_id: str,
    experiment_name: str,
    base_url: str,
    update_uuid: Optional[str],
) -> Path:
    identity = update_uuid or str(Path(run_dir).resolve())
    raw = "\0".join([base_url, user_id, experiment_name, identity])
    key = hashlib.sha256(raw.encode("utf-8")).hexdigest()
    return _cache_dir() / f"{key}.json"


def _load_cache(path: Path) -> Dict[str, Dict[str, Any]]:
    if not path.is_file():
        return {}
    try:
        if time.time() - path.stat().st_mtime > CACHE_MAX_AGE_SECONDS:
            # Server-side shares expire; an old cache must not suppress the
            # re-upload of an otherwise unchanged run.
            return {}
        data = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, ValueError):
        return {}
    if not isinstance(data, dict) or data.get("version") != CACHE_VERSION:
        return {}
    files = data.get("files")
    return files if isinstance(files, dict) else {}


def _save_cache(path: Path, files: Dict[str, Dict[str, Any]]) -> None:
    try:
        path.parent.mkdir(parents=True, exist_ok=True)
        tmp = path.with_name(path.name + ".tmp")
        tmp.write_text(
            json.dumps({"version": CACHE_VERSION, "files": files}, sort_keys=True),
            encoding="utf-8",
        )
        os.replace(tmp, path)
    except OSError as e:
        print(f"Warning: could not write share cache {path}: {e}", file=sys.stderr)


def _file_state(path: Path) -> Dict[str, int]:
    st = path.stat()
    return {
        "size": st.st_size,
        "mtime_ns": getattr(st, "st_mtime_ns", int(st.st_mtime * 1_000_000_000)),
    }


def _split_changed_files(
    files: List[Dict[str, Any]],
    cache: Dict[str, Dict[str, Any]],
) -> Tuple[List[Dict[str, Any]], Dict[str, Dict[str, int]]]:
    """Return (files to upload, pre-upload state of every selected file)."""
    selected: List[Dict[str, Any]] = []
    pre_states: Dict[str, Dict[str, int]] = {}
    for f in files:
        local = Path(f["local_path"])
        try:
            state = _file_state(local)
        except OSError:
            continue
        old = cache.get(f["archive_path"])
        if (
            isinstance(old, dict)
            and old.get("size") == state["size"]
            and old.get("mtime_ns") == state["mtime_ns"]
        ):
            continue
        selected.append(f)
        pre_states[f["archive_path"]] = state
    return selected, pre_states


def _update_cache(
    cache_path: Path,
    old_cache: Dict[str, Dict[str, Any]],
    manifest: Dict[str, Any],
    pre_states: Dict[str, Dict[str, int]],
    source_dir: str,
    *,
    replace: bool,
) -> None:
    new_cache: Dict[str, Dict[str, Any]] = {} if replace else dict(old_cache)
    for entry in manifest["files"]:
        archive_path = entry["archive_path"]
        local = Path(source_dir) / archive_path
        try:
            state = _file_state(local)
        except OSError:
            new_cache.pop(archive_path, None)
            continue
        before = pre_states.get(archive_path)
        if before and (
            before["size"] != state["size"]
            or before["mtime_ns"] != state["mtime_ns"]
        ):
            # The file changed while it was being zipped.  Do not remember it
            # as uploaded, so the next update sends the newer version.
            new_cache.pop(archive_path, None)
            continue
        new_cache[archive_path] = {
            "size": entry["size"],
            "mtime_ns": state["mtime_ns"],
            "sha256": entry["sha256"],
        }
    _save_cache(cache_path, new_cache)


# ---------------------------------------------------------------------------
# Bundle writing
# ---------------------------------------------------------------------------


def write_bundle(
    manifest: Dict[str, Any],
    out_dir: str | os.PathLike,
    *,
    source_dir: Optional[str | os.PathLike] = None,
) -> Tuple[Path, Path]:
    """Write ``manifest.json`` and ``bundle.zip`` to ``out_dir``.

    Returns ``(manifest_path, zip_path)``.

    If ``source_dir`` is provided, every file's local path is resolved
    as ``source_dir / archive_path``.  Otherwise, ``archive_path`` is
    treated as the local path (relative or absolute).
    """
    err = verify_manifest(manifest)
    if err:
        raise ValueError(f"Refusing to write invalid manifest: {err}")

    out_dir = Path(out_dir)
    out_dir.mkdir(parents=True, exist_ok=True)
    manifest_path = out_dir / "manifest.json"
    zip_path = out_dir / "bundle.zip"

    base = Path(source_dir) if source_dir is not None else None
    # Hash and size are computed from the exact bytes that are written into
    # the zip.  This keeps manifest and bundle consistent even if a file is
    # modified (or truncated) between manifest creation and bundling, e.g.
    # while the run is still live and ``worker_usage.csv`` is being updated.
    with zipfile.ZipFile(zip_path, "w") as zf:
        for f in manifest["files"]:
            arc = sanitize_archive_path(f["archive_path"])
            local = (base / arc) if base is not None else Path(arc)
            if not local.is_file():
                raise FileNotFoundError(f"Bundle missing source file: {local}")

            info = zipfile.ZipInfo(arc)
            info.external_attr = 0o600 << 16
            info.compress_type = (
                zipfile.ZIP_DEFLATED
                if local.stat().st_size <= COMPRESS_MAX_SIZE
                else zipfile.ZIP_STORED
            )

            digest = hashlib.sha256()
            size = 0
            with local.open("rb") as src, zf.open(info, "w") as dst:
                for chunk in iter(lambda: src.read(1 << 20), b""):
                    size += len(chunk)
                    if size > MAX_FILE_SIZE:
                        raise ValueError(
                            f"{local} is larger than max {MAX_FILE_SIZE}"
                        )
                    digest.update(chunk)
                    dst.write(chunk)

            f["size"] = size
            f["sha256"] = digest.hexdigest()

    # Re-validate after the authoritative size/hash values have been filled
    # in, then persist exactly the manifest that describes the bundle.
    err = verify_manifest(manifest)
    if err:
        raise ValueError(f"Refusing to write invalid manifest: {err}")
    manifest_path.write_text(json.dumps(manifest, indent=2, sort_keys=True))

    return manifest_path, zip_path


# ---------------------------------------------------------------------------
# CLI / main
# ---------------------------------------------------------------------------


def _build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(
        prog="omniopt_share",
        description="Share OmniOpt runs.",
        add_help=False,
    )
    p.add_argument("--help", action="store_true")
    p.add_argument("--update", action="store_true",
                   help="Update a previously-shared run.")
    p.add_argument("--debug", action="store_true")
    p.add_argument("--no_color", action="store_true")
    p.add_argument("--force", action="store_true",
                   help="Ignore the incremental cache and re-send everything.")
    p.add_argument("--include_state_files", action="store_true",
                   help="Also share state_files/*.json/csv/txt (large "
                        "checkpoints/model snapshots; normally skipped).")
    p.add_argument("--timeout", type=float, default=DEFAULT_POST_TIMEOUT,
                   help=f"HTTP timeout in seconds (default: {DEFAULT_POST_TIMEOUT}).")
    p.add_argument("--username", default=None)
    p.add_argument("--password", default=None)
    p.add_argument("--dont_send_singleruns", action="store_true")
    p.add_argument("--outfile", default=None)
    p.add_argument("run_dirs", nargs="*", default=[],
                   help="One or more run directories to share.")
    return p


def parse_args(argv: Sequence[str]) -> argparse.Namespace:
    args = _build_parser().parse_args(list(argv))
    # Convenience: invert --dont_send_singleruns into a positive bool.
    args.send_single_runs = not args.dont_send_singleruns
    return args


def _print_help() -> None:
    print(
        "Usage: omniopt_share [OPTIONS] RUN_DIR\n"
        "\n"
        "Share your hyperparameter optimization results with others.\n"
        "\n"
        "Example:\n"
        "  omniopt_share runs/my_experiment/0\n"
        "\n"
        "Options:\n"
        "  --update                  Update a job that had this run-UUID.\n"
        "                            Only changed files are uploaded.\n"
        "  --debug                   Enable debug output\n"
        "  --no_color                Disable colored output\n"
        "  --force                   Ignore cache and re-send all files\n"
        "  --include_state_files     Also send state_files snapshots\n"
        "  --timeout=SECONDS         HTTP timeout (default: "
        f"{DEFAULT_POST_TIMEOUT:g})\n"
        "  --username=NAME           Override username\n"
        "  --password=PWD            Set password\n"
        "  --dont_send_singleruns    Skip single-run outputs\n"
        "  --outfile=PATH            Path to the SLURM .out file\n"
        "  --help                    This help\n"
    )


def _read_username_from_cache() -> Optional[str]:
    if DONT_ASK_FILE.exists() and USERNAME_FILE.exists():
        cached = USERNAME_FILE.read_text(encoding="utf-8").strip()
        if is_valid_username(cached):
            return cached
    return None


def _resolve_username(args: argparse.Namespace) -> Optional[str]:
    if args.username:
        if not is_valid_username(args.username):
            print(f"Invalid username: {args.username!r}", file=sys.stderr)
            return None
        return args.username
    return _read_username_from_cache()


def _post_manifest(base_url: str, manifest: Dict[str, Any],
                   bundle_zip: Path, args: argparse.Namespace) -> Tuple[int, str]:
    """Upload ``manifest.json`` + ``bundle.zip`` as multipart POST.

    Returns ``(exit_code, body)``.  Falls back to a JSON POST when no
    bundle is present.
    """
    url = (
        f"{base_url}/share_internal.php"
        f"?user_id={manifest['user_id']}"
        f"&experiment_name={manifest['experiment_name']}"
    )
    if manifest["update"]:
        url += "&update=1"
    if manifest["update_uuid"]:
        url += f"&update_uuid={manifest['update_uuid']}"
    if manifest["password"]:
        url += f"&password={manifest['password']}"

    boundary = "----omniopt-share-" + os.urandom(8).hex()
    content_length, body = _build_multipart_stream(boundary, manifest, bundle_zip)
    req = urllib.request.Request(
        url,
        data=body,
        headers={
            "Content-Type": f"multipart/form-data; boundary={boundary}",
            "Content-Length": str(content_length),
        },
        method="POST",
    )
    timeout = float(getattr(args, "timeout", DEFAULT_POST_TIMEOUT) or DEFAULT_POST_TIMEOUT)
    try:
        with urllib.request.urlopen(req, timeout=timeout) as resp:
            return resp.status, resp.read().decode("utf-8", errors="replace")
    except urllib.error.HTTPError as e:
        return e.code, e.read().decode("utf-8", errors="replace")
    except (urllib.error.URLError, TimeoutError, OSError) as e:
        return 7, f"Connection error: {e}"


def _build_multipart_stream(
    boundary: str, manifest: Dict[str, Any], bundle_zip: Path
) -> Tuple[int, Iterable[bytes]]:
    """Return ``(content_length, chunks)`` for a streaming multipart body.

    The zip is streamed from disk in 1 MiB chunks.  This keeps memory usage
    constant even for very large run directories (the old implementation read
    the whole ``bundle.zip`` into a single ``bytes`` object, then copied it
    again while building the request body).
    """
    prefix = (
        f"--{boundary}\r\n"
        'Content-Disposition: form-data; name="manifest"\r\n'
        "Content-Type: application/json\r\n"
        "\r\n"
    ).encode()
    manifest_bytes = json.dumps(manifest).encode()
    middle = (
        f"\r\n--{boundary}\r\n"
        'Content-Disposition: form-data; name="bundle"; filename="bundle.zip"\r\n'
        "Content-Type: application/zip\r\n"
        "\r\n"
    ).encode()
    suffix = f"\r\n--{boundary}--\r\n".encode()
    zip_size = bundle_zip.stat().st_size
    content_length = (
        len(prefix) + len(manifest_bytes) + len(middle) + zip_size + len(suffix)
    )

    def chunks() -> Iterable[bytes]:
        yield prefix
        yield manifest_bytes
        yield middle
        with bundle_zip.open("rb") as fh:
            for chunk in iter(lambda: fh.read(1 << 20), b""):
                yield chunk
        yield suffix

    return content_length, chunks()


def _resolve_base_url() -> str:
    if BASE_URL_FILE.exists():
        return BASE_URL_FILE.read_text(encoding="utf-8").strip() or DEFAULT_BASE_URL
    return DEFAULT_BASE_URL
def _share_one_with(
    args: argparse.Namespace,
    user_id: str,
    run_dir: str,
    base_url: str,
    *,
    post_manifest: Callable[..., Tuple[int, str]],
) -> int:
    """Variant of :func:`_share_one` that takes an injected HTTP
    transport for testing."""
    if not os.path.isdir(run_dir):
        print(f"{run_dir} does not exist", file=sys.stderr)
        return 1

    experiment_name = os.path.basename(
        os.path.dirname(os.path.abspath(run_dir))
    )
    send_single_runs = not getattr(args, "dont_send_singleruns", False)
    include_state_files = bool(getattr(args, "include_state_files", False))

    run_uuid: Optional[str] = None
    run_uuid_path = Path(run_dir) / "state_files" / "run_uuid"
    if run_uuid_path.is_file():
        try:
            run_uuid = run_uuid_path.read_text(encoding="utf-8").strip() or None
        except OSError:
            run_uuid = None

    all_files = collect_shareable_files(
        run_dir,
        send_single_runs=send_single_runs,
        include_state_files=include_state_files,
    )
    if not all_files:
        print(f"Could not find any files in {run_dir}", file=sys.stderr)
        return 1

    cache_path = _cache_file_path(
        run_dir, user_id, experiment_name, base_url, run_uuid
    )
    cache = _load_cache(cache_path)
    incremental = (
        bool(getattr(args, "update", False))
        and not bool(getattr(args, "force", False))
        and bool(cache)
    )

    if incremental:
        files_to_send, pre_states = _split_changed_files(all_files, cache)
        if not files_to_send:
            print(
                f"Nothing changed in {run_dir}; skipping upload.",
                file=sys.stderr,
            )
            return 0
    else:
        files_to_send = all_files
        pre_states = {}
        for f in all_files:
            try:
                pre_states[f["archive_path"]] = _file_state(Path(f["local_path"]))
            except OSError:
                continue

    manifest = build_manifest(
        run_dir=run_dir,
        user_id=user_id,
        experiment_name=experiment_name,
        update=bool(getattr(args, "update", False)),
        update_uuid=run_uuid,
        password=getattr(args, "password", None),
        send_single_runs=send_single_runs,
        include_state_files=include_state_files,
        files=files_to_send,
    )

    if not manifest["files"]:
        print(f"Could not find any files in {run_dir}", file=sys.stderr)
        return 1

    out_dir = Path(tempfile.mkdtemp(prefix="oo_share_"))
    try:
        try:
            _, zip_path = write_bundle(manifest, out_dir, source_dir=run_dir)
        except ValueError as e:
            print(f"Refusing to share: {e}", file=sys.stderr)
            return 1

        total_size = sum(int(f["size"]) for f in manifest["files"])
        if getattr(args, "debug", False) or total_size >= (1 << 20):
            print(
                f"Uploading {len(manifest['files'])} file(s), "
                f"{total_size / (1 << 20):.1f} MiB"
                + (" (incremental update)" if incremental else "")
                + "...",
                file=sys.stderr,
            )

        status, body = post_manifest(base_url, manifest, zip_path, args)

        if status != 200 or "Error" in body:
            print(body, file=sys.stderr)
            if status == 7:
                print(
                    "Exit code 7 means the server was not reachable. "
                    "Are you online? Is the server properly started?",
                    file=sys.stderr,
                )
            return status if status != 200 else 1

        _update_cache(
            cache_path,
            cache,
            manifest,
            pre_states,
            run_dir,
            replace=not incremental,
        )
        print(body)
        return 0
    finally:
        shutil.rmtree(out_dir, ignore_errors=True)


def _share_one(
    args: argparse.Namespace,
    user_id: str,
    run_dir: str,
    base_url: str,
) -> int:
    """Share a single run_dir; returns 0 on success, non-zero on error."""
    return _share_one_with(
        args, user_id, run_dir, base_url,
        post_manifest=_post_manifest,
    )


def main(
    argv: Optional[Sequence[str]] = None,
    *,
    post_manifest: Optional[Callable[..., Tuple[int, str]]] = None,
) -> int:
    args = parse_args(argv if argv is not None else sys.argv[1:])
    if args.help:
        _print_help()
        return 0
    if not args.run_dirs:
        print("Please run with at least one folder as argument", file=sys.stderr)
        return 1

    user_id = _resolve_username(args)
    if not user_id:
        print("No username (use --username or run interactively once)", file=sys.stderr)
        return 1

    base_url = _resolve_base_url()

    last_rc = 0
    for run_dir in args.run_dirs:
        if post_manifest is not None:
            rc = _share_one_with(args, user_id, run_dir, base_url,
                                post_manifest=post_manifest)
        else:
            rc = _share_one(args, user_id, run_dir, base_url)
        if rc != 0:
            last_rc = rc
    return last_rc


# Legacy alias kept for tests / external callers that still use the
# single-dir API.
_share_one_run_dir = _share_one


if __name__ == "__main__":
    try:
        sys.exit(main())
    except KeyboardInterrupt:
        sys.exit(0)
