llmt-cli 0.2.0__py3-none-any.whl

llmt/doctorcmd.py

@@ -0,0 +1,142 @@
+"""``llmt doctor`` — the seed doctor command (WP-14.4b).
+
+Boring, practical output: one PASS / WARN / FAIL / N-A line per check with a
+one-line fix hint on every non-PASS. ``--json`` emits the same results as a
+machine-readable object and never prompts or reads stdin (doctor never
+prompts at all — it is strictly read-only diagnosis).
+
+Exit codes: 0 = no FAIL found (warnings may exist), 15 = at least one FAIL,
+plus the usual LlmtError codes for expected errors (e.g. bad flags).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from . import doctor
+from .clients import (
+    QBittorrentClient,
+    TransmissionClient,
+    build_client,
+)
+from .output import emit_json, safe_text
+
+
+# --------------------------------------------------------------------------- #
+# argparse wiring (called from cli.build_parser) — same client flags as scan
+# --------------------------------------------------------------------------- #
+
+def add_doctor_args(sp) -> None:
+    sp.add_argument("--client", choices=["qbittorrent", "transmission"],
+                    default=None,
+                    help="Torrent client to diagnose. Default: auto "
+                         "(whichever of --qb-url/--tr-url or LLMT_QB_URL/"
+                         "LLMT_TR_URL is configured).")
+    sp.add_argument("--qb-url", default=None, help="qBittorrent WebUI base "
+                    "URL (env LLMT_QB_URL).")
+    sp.add_argument("--qb-user", default=None, help="qBittorrent user (env "
+                    "LLMT_QB_USER).")
+    sp.add_argument("--qb-pass", default=None, help="qBittorrent password "
+                    "(env LLMT_QB_PASS).")
+    sp.add_argument("--tr-url", default=None, help="Transmission RPC URL "
+                    "(env LLMT_TR_URL).")
+    sp.add_argument("--tr-user", default=None, help="Transmission user (env "
+                    "LLMT_TR_USER).")
+    sp.add_argument("--tr-pass", default=None, help="Transmission password "
+                    "(env LLMT_TR_PASS).")
+    sp.add_argument("--hash", action="append", default=[],
+                    help="Only examine the torrent with this info-hash "
+                         "(repeatable). Default: every torrent in the "
+                         "client.")
+    sp.add_argument("--layout-base", default=None,
+                    help="Root of llmt's seeding link farms "
+                         "(default ~/.llmt/seeding-layouts) — used to "
+                         "recognize llmt-planned layouts and to check the "
+                         "farm is visible from the client's filesystem.")
+
+
+# --------------------------------------------------------------------------- #
+# source selection (read-only wrappers over the frozen adapters)
+# --------------------------------------------------------------------------- #
+
+def build_source(args) -> doctor.DoctorSource:
+    """Reuse the frozen ``build_client`` flag/env resolution, then wrap the
+    resulting adapter in a read-only doctor source. No client configured is
+    NOT an error here — it becomes a FAIL on the client-reachable check."""
+    client = build_client(args)
+    if isinstance(client, QBittorrentClient):
+        return doctor.QbtDoctorSource(client)
+    if isinstance(client, TransmissionClient):
+        return doctor.TransmissionDoctorSource(client)
+    return doctor.NullDoctorSource()
+
+
+# --------------------------------------------------------------------------- #
+# command
+# --------------------------------------------------------------------------- #
+
+def cmd_doctor(args) -> int:
+    return run_doctor(args)
+
+
+def run_doctor(args, *, source: Optional[doctor.DoctorSource] = None) -> int:
+    as_json = getattr(args, "json", False)
+    source = source or build_source(args)
+    hashes = {h.strip().lower() for h in (getattr(args, "hash", None) or [])
+              if h.strip()} or None
+
+    snap = source.snapshot(hashes=hashes)
+    results = doctor.run_checks(snap, layout_base=args.layout_base)
+    summary = doctor.summarize(results)
+
+    if as_json:
+        emit_json({
+            "client": {
+                "kind": snap.kind,
+                "endpoint": snap.endpoint,
+                "reachable": snap.reachable,
+                "version": snap.version,
+            },
+            "torrents_examined": len(snap.torrents),
+            "checks": [r.to_dict() for r in results],
+            "summary": summary,
+            "ok": summary["ok"],
+        })
+    else:
+        _print_report(snap, results, summary, hashes)
+
+    return 0 if summary["ok"] else doctor.EXIT_DOCTOR_FAIL
+
+
+def _print_report(snap, results, summary, hashes) -> None:
+    print(f"llmt doctor — {snap.kind} at {safe_text(snap.endpoint)}")
+    print("(signals are the client's own self-reported view unless a check "
+          "says otherwise)")
+    client_rows = [r for r in results if r.scope == "client"]
+    torrent_rows = [r for r in results if r.scope != "client"]
+
+    print("\nClient:")
+    for r in client_rows:
+        _print_row(r)
+
+    if snap.reachable and not snap.torrents:
+        print("\nNo torrents "
+              + ("matched the --hash filter." if hashes
+                 else "found in the client."))
+    scope = None
+    for r in torrent_rows:
+        if r.scope != scope:
+            scope = r.scope
+            print(f"\nTorrent: {safe_text(scope)}")
+        _print_row(r)
+
+    verdict = ("OK — no failures found"
+               if summary["ok"] else "PROBLEMS FOUND")
+    print(f"\nSummary: {summary['pass']} pass, {summary['warn']} warn, "
+          f"{summary['fail']} fail, {summary['na']} n/a -> {verdict}")
+
+
+def _print_row(r) -> None:
+    print(f"  [{r.status}] {r.check}: {safe_text(r.detail)}")
+    if r.status != doctor.PASS and r.hint:
+        print(f"        fix: {safe_text(r.hint)}")

llmt/download.py

@@ -0,0 +1,321 @@
+"""aria2c invocation builder + runner for torrent+webseed downloads.
+
+We delegate the actual BitTorrent transfer to ``aria2c``, which natively
+supports magnet URIs, extra BT trackers (``--bt-tracker``), and HTTP/FTP
+webseeds. The webseeds are the whole point: they let a brand-new download
+saturate bandwidth from the project's HTTP mirrors even before a peer appears
+in the swarm.
+
+How webseeds reach aria2c
+-------------------------
+For a magnet download aria2c fetches the metadata, then downloads the torrent's
+files. Any extra ``http(s)://`` URIs passed on the same invocation are attached
+as **web-seeds** (BEP-19 "GetRight" style) and used as HTTP mirrors for the
+torrent payload alongside BT peers. So the argv is::
+
+    aria2c --dir <out> [--bt-tracker <t> ...] <magnet> <webseed_url> ...
+
+This module only *builds* the argv and shells out. It never parses secrets and
+never fabricates a magnet — the magnet always comes from the API.
+"""
+
+from __future__ import annotations
+
+import base64
+import glob
+import hashlib
+import os
+import shutil
+import subprocess
+import tempfile
+from typing import Optional
+from urllib.parse import parse_qsl, urlsplit
+
+from .errors import MissingDependencyError
+from .clients import ClientError, validate_magnet
+
+
+def ensure_aria2c() -> str:
+    exe = shutil.which("aria2c")
+    if not exe:
+        raise MissingDependencyError(
+            "aria2c is not installed. Install it (e.g. `apt install aria2`, "
+            "`brew install aria2`) and re-run. llmt delegates the torrent + "
+            "webseed transfer to aria2c."
+        )
+    return exe
+
+
+def validate_webseed(url: object) -> str:
+    """Return ``url`` iff it is a safe http(s) web-seed, else raise.
+
+    Anti-injection (C1): API-supplied webseeds are appended to the aria2c argv
+    as positional URIs. aria2c's getopt permutation would parse a token that
+    begins with ``-`` (e.g. ``--on-download-complete=...``) as an OPTION even
+    though it is passed in list-form argv, which is a remote-code-execution /
+    arbitrary-write vector. We therefore refuse anything that is not a bare
+    ``http(s)://`` URL: reject option-looking tokens, whitespace/control
+    chars, non-http(s) schemes, and embedded userinfo credentials.
+    """
+    if not isinstance(url, str) or not url:
+        raise ClientError("refusing an empty/invalid webseed from the API.")
+    if url.startswith("-"):
+        raise ClientError(
+            "refusing a webseed that looks like a command-line option "
+            "(anti-injection).")
+    if any(c in url for c in (" ", "\n", "\r", "\t", "\x00")):
+        raise ClientError(
+            "refusing a webseed containing whitespace/control chars.")
+    parsed = urlsplit(url)
+    if parsed.scheme not in ("http", "https"):
+        raise ClientError(
+            "refusing a webseed with a non-http(s) scheme (anti-injection).")
+    if "@" in parsed.netloc:
+        raise ClientError(
+            "refusing a webseed whose URL carries userinfo credentials "
+            "(credential-smuggling defense).")
+    return url
+
+
+def build_aria2c_args(
+    magnet: str,
+    out_dir: str,
+    webseeds: Optional[list[str]] = None,
+    trackers: Optional[list[str]] = None,
+    seed: bool = False,
+    exe: str = "aria2c",
+    metadata_only: bool = False,
+) -> list[str]:
+    """Construct the exact aria2c argv for a webseed-backed torrent download.
+
+    - ``magnet``   : API-supplied magnet URI (never fabricated).
+    - ``webseeds`` : HTTP mirrors, appended as trailing URIs so aria2c uses
+                     them as web-seeds for the torrent's files.
+    - ``trackers`` : extra BT trackers, each via ``--bt-tracker``.
+    - ``seed``     : when True, keep seeding after completion; when False,
+                     exit as soon as the download finishes.
+    - ``metadata_only`` : resolve the magnet to its ``.torrent`` (BEP-9
+                     metadata) and exit WITHOUT downloading payload; used to
+                     hand a client a ``.torrent`` instead of a magnet.
+    """
+    if metadata_only:
+        # Same hardened choke point as the download path: validate the magnet
+        # and put a literal ``--`` end-of-options separator before it. No
+        # webseeds (they serve payload, not metadata) and no payload/seed
+        # flags. aria2c saves ``<info-hash>.torrent`` into out_dir and exits.
+        magnet = validate_magnet(magnet)
+        meta_args: list[str] = [
+            exe,
+            "--dir", out_dir,
+            "--bt-metadata-only=true",
+            "--bt-save-metadata=true",
+            "--enable-dht=true",
+            "--bt-enable-lpd=true",
+            "--follow-torrent=mem",
+            "--seed-time=0",
+            "--summary-interval=0",
+        ]
+        for t in trackers or []:
+            meta_args += ["--bt-tracker", t]
+        meta_args.append("--")
+        meta_args.append(magnet)
+        return meta_args
+    args: list[str] = [
+        exe,
+        "--dir", out_dir,
+        "--enable-dht=true",
+        "--bt-enable-lpd=true",
+        "--follow-torrent=mem",
+        "--check-integrity=true",   # aria2c's own piece-hash check (belt);
+                                    # llmt still runs a full sha256 pass (braces)
+        "--max-connection-per-server=8",
+        "--min-split-size=1M",
+        "--summary-interval=10",
+    ]
+    for t in trackers or []:
+        args += ["--bt-tracker", t]
+
+    if seed:
+        # aria2c seeds indefinitely after completion when neither --seed-time
+        # nor --seed-ratio caps it; keep verified seeding on so we only ever
+        # share correct pieces.
+        args += ["--bt-seed-unverified=false"]
+    else:
+        # Do not linger seeding once the payload is complete.
+        args += ["--seed-time=0"]
+
+    # Validate the API-supplied magnet + webseeds BEFORE they reach aria2c.
+    # Both the pull and seed paths funnel through here, so this is the single
+    # choke point that closes the aria2c argument-injection hole (C1/H1):
+    #   * validate_magnet rejects any non-``magnet:?`` / option-looking value;
+    #   * validate_webseed rejects any webseed that could act as an option.
+    magnet = validate_magnet(magnet)
+    safe_webseeds = [validate_webseed(w) for w in (webseeds or [])]
+
+    # Positional URIs: a literal ``--`` end-of-options separator FIRST, so that
+    # nothing after it can be parsed as an option even if validation is ever
+    # loosened (defense in depth), then the magnet, then the webseeds
+    # (attached as web-seeds).
+    args.append("--")
+    args.append(magnet)
+    for w in safe_webseeds:
+        args.append(w)
+    return args
+
+
+def run_aria2c(args: list[str]) -> int:
+    """Run aria2c, streaming its output to the terminal; return its exit code."""
+    return subprocess.run(args).returncode
+
+
+# --------------------------------------------------------------------------- #
+# Magnet -> .torrent resolution (Fix 14A-12)
+#
+# The docker harness (docs/HARNESS-magnet-metadata.md) proved that qBittorrent
+# 4.6/5.x and Transmission do NOT fetch magnet metadata while a torrent is
+# added paused/stopped -- so the paused-add handoff would hang at the metadata
+# gate forever. We therefore resolve the magnet to a ``.torrent`` up front with
+# aria2c (metadata-only, no payload) and hand the client the ``.torrent``; its
+# piece layout is then known at add time. Resolution goes through the SAME
+# hardened ``build_aria2c_args`` choke point (validate_magnet + literal ``--``),
+# is bounded by a timeout, and fails closed -- the magnet is never handed to a
+# client if resolution does not produce a matching ``.torrent``.
+# --------------------------------------------------------------------------- #
+
+MAGNET_RESOLVE_TIMEOUT = 180  # seconds; bounded, honest ClientError on expiry
+
+
+def _bdecode(data: bytes):
+    def parse(i):
+        c = data[i:i + 1]
+        if c == b"i":
+            j = data.index(b"e", i)
+            return int(data[i + 1:j]), j + 1
+        if c == b"l":
+            i += 1
+            out = []
+            while data[i:i + 1] != b"e":
+                v, i = parse(i)
+                out.append(v)
+            return out, i + 1
+        if c == b"d":
+            i += 1
+            out = {}
+            while data[i:i + 1] != b"e":
+                k, i = parse(i)
+                v, i = parse(i)
+                out[k] = v
+            return out, i + 1
+        j = data.index(b":", i)
+        n = int(data[i:j])
+        return data[j + 1:j + 1 + n], j + 1 + n
+    return parse(0)[0]
+
+
+def _bencode(obj) -> bytes:
+    if isinstance(obj, bool):
+        raise TypeError("bool is not bencodable")
+    if isinstance(obj, int):
+        return b"i" + str(obj).encode() + b"e"
+    if isinstance(obj, bytes):
+        return str(len(obj)).encode() + b":" + obj
+    if isinstance(obj, str):
+        b = obj.encode()
+        return str(len(b)).encode() + b":" + b
+    if isinstance(obj, list):
+        return b"l" + b"".join(_bencode(x) for x in obj) + b"e"
+    if isinstance(obj, dict):
+        items = sorted(obj.items(),
+                       key=lambda kv: kv[0] if isinstance(kv[0], bytes)
+                       else str(kv[0]).encode())
+        return b"d" + b"".join(_bencode(k) + _bencode(v)
+                               for k, v in items) + b"e"
+    raise TypeError("unbencodable: %r" % (type(obj),))
+
+
+def _infohash_v1(torrent_bytes: bytes) -> str:
+    """SHA-1 of the bencoded ``info`` dict (BitTorrent v1 info-hash, hex)."""
+    meta = _bdecode(torrent_bytes)
+    if not isinstance(meta, dict) or b"info" not in meta:
+        raise ClientError(
+            "the .torrent aria2c produced has no info dict -- refusing to hand "
+            "it to the client; NOT seeding.")
+    return hashlib.sha1(_bencode(meta[b"info"])).hexdigest()
+
+
+def _magnet_btih(magnet: str) -> Optional[str]:
+    """Return the v1 info-hash (40-hex, lowercase) named by the magnet's
+    ``xt=urn:btih:`` (hex or base32), or None (e.g. a v2-only ``btmh`` magnet)."""
+    try:
+        pairs = parse_qsl(urlsplit(magnet).query, keep_blank_values=True)
+    except ValueError:
+        return None
+    for k, v in pairs:
+        if k == "xt" and v.lower().startswith("urn:btih:"):
+            h = v.split("urn:btih:", 1)[1]
+            if len(h) == 40 and all(c in "0123456789abcdefABCDEF" for c in h):
+                return h.lower()
+            if len(h) == 32:
+                try:
+                    return base64.b32decode(h.upper()).hex()
+                except Exception:
+                    return None
+    return None
+
+
+def run_aria2c_metadata(args: list[str], timeout: int) -> int:
+    """Run the metadata-only aria2c argv, bounded by ``timeout``. Returns the
+    exit code; raises ClientError (fail closed) if the bound is exceeded."""
+    try:
+        proc = subprocess.run(args, stdout=subprocess.PIPE,
+                              stderr=subprocess.STDOUT, timeout=timeout)
+        return proc.returncode
+    except subprocess.TimeoutExpired:
+        raise ClientError(
+            f"timed out resolving the magnet to a .torrent via aria2c after "
+            f"~{timeout}s; the magnet was NOT handed to the client and it is "
+            "NOT seeding.")
+
+
+def resolve_magnet_to_torrent(magnet: str, info_hash: Optional[str] = None, *,
+                              timeout: int = MAGNET_RESOLVE_TIMEOUT,
+                              exe: Optional[str] = None) -> bytes:
+    """Resolve ``magnet`` to ``.torrent`` bytes via aria2c metadata-only.
+
+    Fails closed: any resolution failure (aria2c missing, non-zero exit, no
+    metadata produced, timeout, or an info-hash that does not match the
+    requested torrent) raises ClientError so the caller NEVER hands a client a
+    magnet the current clients cannot resolve while paused.
+    """
+    magnet = validate_magnet(magnet)
+    exe = exe or ensure_aria2c()
+    workdir = tempfile.mkdtemp(prefix="llmt-magnetmeta-")
+    try:
+        args = build_aria2c_args(magnet, workdir, metadata_only=True, exe=exe)
+        rc = run_aria2c_metadata(args, timeout)
+        produced = sorted(glob.glob(os.path.join(workdir, "*.torrent")))
+        if rc != 0 or not produced:
+            raise ClientError(
+                f"aria2c could not resolve the magnet to a .torrent (exit "
+                f"{rc}); the magnet was NOT handed to the client and it is NOT "
+                "seeding.")
+        with open(produced[0], "rb") as fh:
+            torrent_bytes = fh.read()
+        # Anti-substitution: the resolved .torrent MUST be the requested
+        # torrent. aria2c already validates ut_metadata against the magnet's
+        # info-hash, but we re-check here as defense in depth before any handoff.
+        expected = _magnet_btih(magnet)
+        if expected is None and info_hash:
+            ih = str(info_hash).lower()
+            expected = ih if (len(ih) == 40
+                              and all(c in "0123456789abcdef" for c in ih)) else None
+        if expected is not None:
+            got = _infohash_v1(torrent_bytes)
+            if got != expected:
+                raise ClientError(
+                    "the .torrent aria2c resolved does not match the requested "
+                    f"info-hash (got {got}, expected {expected}) -- refusing "
+                    "to hand it to the client; NOT seeding.")
+        return torrent_bytes
+    finally:
+        shutil.rmtree(workdir, ignore_errors=True)

llmt/errors.py

@@ -0,0 +1,132 @@
+"""Typed errors for the llmt CLI.
+
+Every user-facing failure raises one of these so ``cli.main`` can print a
+clean, single-line message and pick the right non-zero exit code — the CLI
+never shows a raw traceback for an expected condition (API 4xx/5xx/timeout,
+a license gate, or a hash mismatch).
+"""
+
+from __future__ import annotations
+
+
+class LlmtError(Exception):
+    """Base for all expected CLI errors. exit_code drives sys.exit()."""
+
+    exit_code = 1
+
+
+class ApiError(LlmtError):
+    """The API returned an error envelope or an unexpected HTTP status."""
+
+    def __init__(self, message: str, *, code: str | None = None,
+                 status: int | None = None, details: dict | None = None):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.details = details or {}
+    exit_code = 2
+
+
+class NotFoundError(ApiError):
+    """404 — unknown model / manifest / quant."""
+
+    exit_code = 4
+
+
+class RateLimitedError(ApiError):
+    """429 — includes Retry-After seconds when the server supplied it."""
+
+    def __init__(self, message: str, *, retry_after: int | None = None, **kw):
+        super().__init__(message, **kw)
+        self.retry_after = retry_after
+    exit_code = 5
+
+
+class TimeoutErrorLlmt(ApiError):
+    """The API did not respond within the timeout."""
+
+    exit_code = 6
+
+
+class LicenseGatedError(LlmtError):
+    """D7 — the model/quant is license-gated; no artifacts are served.
+
+    Carries ONLY the human model_page URL. It never carries (or lets the
+    caller fabricate) a magnet, info hash, file path or sha256.
+    """
+
+    def __init__(self, slug: str, model_page: str | None):
+        self.slug = slug
+        self.model_page = model_page
+        msg = (f"'{slug}' is license-gated. The catalog API does not serve "
+               f"download artifacts for gated models.")
+        super().__init__(msg)
+    exit_code = 7
+
+
+class NotAvailableError(LlmtError):
+    """The quant has no gate-passed torrent to download."""
+
+    exit_code = 8
+
+
+class VerificationError(LlmtError):
+    """One or more files failed SHA-256 verification. THE trust signal."""
+
+    exit_code = 3
+
+
+class MissingDependencyError(LlmtError):
+    """A required external tool (aria2c) is not installed."""
+
+    exit_code = 9
+
+
+class LayoutError(LlmtError):
+    """Base for seeding-layout mapper failures (WP-14.2b)."""
+
+    exit_code = 10
+
+
+class LayoutSafetyError(LayoutError):
+    """An in-torrent path failed the untrusted-input safety checks.
+
+    Raised for path traversal (``..``), absolute/drive-letter/UNC tricks,
+    embedded nulls or control chars, reserved device names, or a planned
+    link whose destination would escape the layouts base dir.
+    """
+
+    exit_code = 11
+
+
+class LayoutSourceError(LayoutError):
+    """The user's local artifact is missing or not a regular file."""
+
+    exit_code = 12
+
+
+class LayoutApplyError(LayoutError):
+    """A mkdir/hardlink/symlink action failed, or an existing link points at
+    the WRONG target (we never silently replace it)."""
+
+    def __init__(self, message: str, *, hint: str | None = None):
+        self.hint = hint
+        super().__init__(message if not hint else f"{message} Hint: {hint}")
+
+    exit_code = 13
+
+
+class ManifestVerificationError(LlmtError):
+    """The Ed25519-signed manifest could not be obtained or did not verify.
+
+    Fail-closed authenticity signal for ``pull``/``verify``/``seed`` (Fix
+    M2, Option A): if the manifest is unreachable (including offline),
+    malformed, signed with an unknown or wrong key, carries a bad
+    signature, names a different torrent, or disagrees with the catalog's
+    file list, NOTHING is reported as "verified" and no seed starts. The
+    message always states the specific reason; there is no silent
+    downgrade to unauthenticated (TLS-only) hash checking.
+    """
+
+    code = "manifest_unverified"
+    exit_code = 15