tony-cli 0.3.0__py3-none-any.whl

tony_cli/hosted.py

@@ -0,0 +1,324 @@
+"""Publishing to the tony site.
+
+The payload is uploaded as JSON over TLS and sealed by the server before it
+reaches storage. An earlier design encrypted here and put the key in the URL
+fragment so the site could never read a review; that was dropped deliberately
+when reading was gated behind an account and a history of past reviews became
+part of the product — both require the server to be able to open a review.
+So: reviews are confidential against a leak of the stored blobs, not against
+the site itself. `tony --publish` says as much the first time you use it.
+
+Login is GitHub's device flow, the same shape as `gh auth login`: tony prints a
+code, you approve it in a browser, tony polls. The GitHub token is traded to the
+tony API for tony's own token, which is what gets cached — the GitHub token is
+never stored.
+"""
+
+import gzip
+import json
+import os
+import stat
+import sys
+import time
+
+import httpx
+
+GITHUB_DEVICE_CODE = "https://github.com/login/device/code"
+GITHUB_DEVICE_TOKEN = "https://github.com/login/oauth/access_token"
+
+# The site tony publishes to. Overridable for local development, but it has a
+# real default because publishing is the default path — a fresh install should
+# work without anyone setting an environment variable.
+DEFAULT_API_URL = "https://tony-cli.com"
+
+CONFIG_DIR = os.path.expanduser(os.path.join("~", ".tony"))
+CREDENTIALS = os.path.join(CONFIG_DIR, "credentials.json")
+
+
+def asJson(response):
+    """A response's JSON body, or None if it is not JSON.
+
+    `httpx` raises `json.JSONDecodeError` rather than an `HTTPError` here, so
+    every bare `.json()` was one HTML error page away from a traceback.
+    """
+    try:
+        body = response.json()
+    except ValueError:
+        return None
+    return body if isinstance(body, dict) else None
+
+
+def apiBase():
+    """Where the tony site lives."""
+    return (os.environ.get("TONY_API_URL") or DEFAULT_API_URL).rstrip("/")
+
+
+# --- credentials -----------------------------------------------------------
+
+def savedToken():
+    try:
+        with open(CREDENTIALS, encoding="utf-8") as fh:
+            return json.load(fh).get("token")
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def saveToken(token, login):
+    """Write the credential, never leaving it readable by anyone else.
+
+    `open()` would create at the umask's mercy — 0644 on most machines — and a
+    chmod afterwards closes the window a moment too late. Opening with the mode
+    up front means the file is never readable by another user on a shared box.
+    """
+    os.makedirs(CONFIG_DIR, mode=0o700, exist_ok=True)
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+    fd = os.open(CREDENTIALS, flags, stat.S_IRUSR | stat.S_IWUSR)
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        json.dump({"token": token, "githubLogin": login}, fh)
+
+
+def clearToken():
+    try:
+        os.remove(CREDENTIALS)
+        return True
+    except OSError:
+        return False
+
+
+# --- login -----------------------------------------------------------------
+
+def login():
+    """GitHub device flow, then trade the GitHub token for a tony API token.
+
+    Returns 0 on success, non-zero on failure, and prints its own messages —
+    this is a user-facing command, not a library call.
+    """
+    base = apiBase()
+    if not base:
+        print("tony: TONY_API_URL is not set — there is no site to log in to yet.",
+              file=sys.stderr)
+        return 2
+
+    # The GitHub OAuth client id is public by design; the server owns it so the
+    # CLI never has to ship one.
+    try:
+        config = asJson(httpx.get(f"{base}/api/config", timeout=10)) or {}
+        clientId = config.get("githubClientId") or ""
+    except Exception as e:
+        print(f"tony: could not reach {base}: {e}", file=sys.stderr)
+        return 1
+    if not clientId:
+        print("tony: the site has no GitHub app configured, so login cannot start.",
+              file=sys.stderr)
+        return 1
+
+    try:
+        device = asJson(httpx.post(
+            GITHUB_DEVICE_CODE,
+            data={"client_id": clientId, "scope": "read:user"},
+            headers={"Accept": "application/json"},
+            timeout=10,
+        )) or {}
+    except httpx.HTTPError as e:
+        print(f"tony: could not reach GitHub: {e}", file=sys.stderr)
+        return 1
+
+    # A GitHub OAuth app has device flow OFF by default, and that shows up
+    # here rather than at approval time. Say which switch is missing instead
+    # of dying on a missing key.
+    if "user_code" not in device:
+        detail = device.get("error_description") or device.get("error") or "unknown error"
+        print(f"tony: GitHub would not start a device login — {detail}.", file=sys.stderr)
+        if device.get("error") == "device_flow_disabled":
+            print("      Enable 'Device flow' in the GitHub OAuth app's settings.",
+                  file=sys.stderr)
+        return 1
+
+    print(f"\n  First, copy this code: {device['user_code']}")
+    print(f"  Then approve it at:    {device['verification_uri']}\n")
+    print("  Waiting for approval — press Ctrl-C to give up.", file=sys.stderr)
+
+    interval = int(device.get("interval", 5))
+    deadline = time.time() + int(device.get("expires_in", 900))
+    githubToken = None
+    try:
+        while time.time() < deadline:
+            time.sleep(interval)
+            try:
+                poll = asJson(httpx.post(
+                    GITHUB_DEVICE_TOKEN,
+                    data={
+                        "client_id": clientId,
+                        "device_code": device["device_code"],
+                        "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                    },
+                    headers={"Accept": "application/json"},
+                    timeout=10,
+                )) or {}
+            except httpx.HTTPError:
+                # A blip mid-approval should not lose a code the user already
+                # typed in; the deadline still bounds this.
+                continue
+
+            error = poll.get("error")
+            if error == "authorization_pending":
+                continue
+            if error == "slow_down":
+                interval += 5
+                continue
+            if error == "expired_token":
+                break
+            if error:
+                detail = poll.get("error_description") or error
+                print(f"tony: GitHub declined the login — {detail}.", file=sys.stderr)
+                return 1
+            githubToken = poll.get("access_token")
+            break
+    except KeyboardInterrupt:
+        print("\ntony: login cancelled.", file=sys.stderr)
+        return 1
+
+    if not githubToken:
+        print("tony: the code expired before it was approved. Run tony login again.",
+              file=sys.stderr)
+        return 1
+
+    try:
+        exchanged = httpx.post(
+            f"{base}/api/auth/github",
+            json={"accessToken": githubToken},
+            timeout=15,
+        )
+    except httpx.HTTPError as e:
+        print(f"tony: approved, but could not reach {base}: {e}", file=sys.stderr)
+        return 1
+    if exchanged.status_code != 200:
+        print(f"tony: the tony API rejected the login ({exchanged.status_code}).",
+              file=sys.stderr)
+        return 1
+
+    body = asJson(exchanged) or {}
+    if not body.get("token"):
+        print("tony: the tony API returned no token.", file=sys.stderr)
+        return 1
+    saveToken(body["token"], body.get("githubLogin", ""))
+    print(f"tony: logged in as {body.get('githubLogin', 'you')}.")
+    return 0
+
+
+def whoami():
+    """Who this machine is logged in as, if anyone."""
+    try:
+        with open(CREDENTIALS, encoding="utf-8") as fh:
+            saved = json.load(fh)
+    except (OSError, json.JSONDecodeError):
+        print("tony: not logged in. Run `tony login` to publish reviews.")
+        return 1
+    print(f"tony: logged in as {saved.get('githubLogin') or 'unknown'}.")
+    return 0
+
+
+def logout():
+    """Revoke this machine's token server-side, then forget it locally.
+
+    Deleting the local file alone would leave a working token in anyone's hands
+    who had already copied it, so the revoke comes first — but a site that is
+    unreachable must not strand someone logged in on a laptop they are trying
+    to wipe, so local removal happens either way.
+    """
+    token = savedToken()
+    if token and apiBase():
+        try:
+            httpx.post(
+                f"{apiBase()}/api/auth/logout",
+                headers={"Authorization": f"Bearer {token}"},
+                timeout=10,
+            )
+        except httpx.HTTPError:
+            print("tony: could not reach the site to revoke this token; "
+                  "removing it locally anyway.", file=sys.stderr)
+
+    if clearToken():
+        print("tony: logged out.")
+    else:
+        print("tony: you were not logged in.")
+    return 0
+
+
+# --- encrypt and upload ----------------------------------------------------
+
+def publish(payloadJson, repo="", rangeLabel=""):
+    """Upload one payload. Returns (url, problem)."""
+    base = apiBase()
+    if not base:
+        return None, (
+            "TONY_API_URL is not set. Publishing needs a deployed tony site — "
+            "the local page in .tony/ works without one."
+        )
+    token = savedToken()
+    if not token:
+        return None, "not logged in — run `tony login` first."
+
+    # Gzip before upload. Review JSON is repetitive source and compresses about
+    # ten to one, and the site's size limit is measured on what arrives — so
+    # this is what lets a large review publish at all, not just a smaller
+    # request. `application/gzip` rather than `Content-Encoding`, so no proxy
+    # decides to helpfully inflate it on the way.
+    try:
+        resp = httpx.post(
+            f"{base}/api/reviews",
+            content=gzip.compress(payloadJson.encode("utf-8")),
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/gzip",
+            },
+            timeout=60,
+        )
+    except httpx.HTTPError as e:
+        return None, f"could not reach {base}: {e}"
+
+    if resp.status_code == 401:
+        return None, "your login expired — run `tony login` again."
+    if resp.status_code == 413:
+        return None, "this review is over the upload size limit."
+    if resp.status_code != 200:
+        return None, f"upload failed ({resp.status_code})."
+
+    body = asJson(resp) or {}
+    if not body.get("id"):
+        return None, "the site accepted the upload but returned no review id."
+    print(f"tony: to remove it later: tony unpublish {body['id']}", file=sys.stderr)
+    return f"{base}/r/{body['id']}", None
+
+
+def unpublish(reviewId):
+    """Delete one of your own published reviews."""
+    base = apiBase()
+    if not base:
+        print("tony: TONY_API_URL is not set.", file=sys.stderr)
+        return 2
+    token = savedToken()
+    if not token:
+        print("tony: not logged in — run `tony login` first.", file=sys.stderr)
+        return 2
+    try:
+        resp = httpx.request(
+            "DELETE",
+            f"{base}/api/reviews/{reviewId}",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=15,
+        )
+    except httpx.HTTPError as e:
+        print(f"tony: could not reach {base}: {e}", file=sys.stderr)
+        return 1
+
+    if resp.status_code == 200:
+        print("tony: removed.")
+        return 0
+    if resp.status_code == 403:
+        print("tony: that review belongs to someone else.", file=sys.stderr)
+    elif resp.status_code == 404:
+        print("tony: no such review.", file=sys.stderr)
+    else:
+        print(f"tony: could not remove it ({resp.status_code}).", file=sys.stderr)
+    return 1

tony_cli/install.py

@@ -0,0 +1,138 @@
+"""How this copy of tony was installed, and how to change it.
+
+`tony --update` and `tony uninstall` both have to answer the same question
+first: which tool put this here? Guessing from PATH picks whichever installer
+the user happens to also have, so both read the receipt the installer left at
+the root of the environment tony is actually running from.
+"""
+
+import os
+import subprocess
+import sys
+
+import httpx
+
+PKG = "tony-cli"
+
+# The same pinning install.sh does, for the same reason: both installers honour
+# an ambient index setting, so on a machine pointed at an internal mirror an
+# update would pull whatever that mirror serves under the name `tony-cli`.
+INDEX = "https://pypi.org/simple"
+RELEASES = "https://pypi.org/pypi/tony-cli/json"
+
+
+def indexEnv():
+    env = dict(os.environ)
+    env["UV_INDEX_URL"] = INDEX
+    env["UV_DEFAULT_INDEX"] = INDEX
+    env["PIP_INDEX_URL"] = INDEX
+    return env
+
+
+def isSourceCheckout():
+    """True when running from `pip install -e .` in tony's own repo.
+
+    Neither updating nor uninstalling may touch a working tree: one would
+    overwrite uncommitted work, the other would delete it.
+    """
+    pkg = os.path.dirname(os.path.abspath(__file__))
+    return os.path.exists(os.path.join(pkg, "..", "..", "pyproject.toml"))
+
+
+def installer():
+    """'uv', 'pipx', or 'pip' — whichever environment tony is running from."""
+    if os.path.exists(os.path.join(sys.prefix, "uv-receipt.toml")):
+        return "uv"
+    if os.path.exists(os.path.join(sys.prefix, "pipx_metadata.json")):
+        return "pipx"
+    return "pip"
+
+
+def uninstallCommand(kind):
+    if kind == "uv":
+        return ["uv", "tool", "uninstall", PKG]
+    if kind == "pipx":
+        return ["pipx", "uninstall", PKG]
+    return [sys.executable, "-m", "pip", "uninstall", "-y", PKG]
+
+
+def updateCommand(kind):
+    if kind == "uv":
+        return ["uv", "tool", "upgrade", PKG]
+    if kind == "pipx":
+        return ["pipx", "upgrade", PKG]
+    return [sys.executable, "-m", "pip", "install", "--upgrade", PKG]
+
+
+def installedVersion():
+    """The running version, or None if the metadata is not there to read."""
+    try:
+        from importlib.metadata import version
+        return version(PKG)
+    except Exception:
+        return None
+
+
+def latestVersion(timeout=10):
+    """The newest version PyPI serves, or None if it cannot be asked.
+
+    Worth one request: without it there is nothing to check the upgrade
+    against, and every installer exits 0 for "already at latest" — which is
+    indistinguishable from "upgraded" unless you knew the target beforehand.
+    """
+    try:
+        response = httpx.get(RELEASES, timeout=timeout)
+        if response.status_code != 200:
+            return None
+        return ((response.json() or {}).get("info") or {}).get("version")
+    except Exception:
+        return None
+
+
+def update(argv=()):
+    """`tony update`. Returns an exit code, prints its own messages."""
+    if argv:
+        print("usage: tony update", file=sys.stderr)
+        return 2
+
+    if isSourceCheckout():
+        print(f"tony: this is a source checkout at {sys.prefix} — update it with "
+              "`git pull`, not from PyPI.", file=sys.stderr)
+        return 2
+
+    kind = installer()
+    command = updateCommand(kind)
+    before = installedVersion()
+    latest = latestVersion()
+
+    # Nothing to do is worth saying out loud. Running the installer anyway
+    # prints a wall of its output and exits 0, which reads exactly like a
+    # successful upgrade.
+    if latest and before and latest == before:
+        print(f"tony: already on the latest version ({before}).")
+        return 0
+
+    target = f" to {latest}" if latest else ""
+    print(f"tony: {before or 'unknown version'}, updating{target} with {kind}...")
+    # The installer writes to this same terminal; without a flush its output
+    # arrives before the line announcing it.
+    sys.stdout.flush()
+
+    try:
+        result = subprocess.run(command, env=indexEnv())
+    except OSError as e:
+        print(f"tony: could not run {command[0]}: {e}", file=sys.stderr)
+        print(f"tony: update by hand with: {' '.join(command)}", file=sys.stderr)
+        return 1
+    if result.returncode != 0:
+        print(f"tony: {kind} could not update tony.", file=sys.stderr)
+        return result.returncode
+
+    # This interpreter still has the old version loaded, so it cannot read the
+    # new one back. PyPI's answer is the honest thing to report; without it,
+    # say what happened rather than asserting an outcome.
+    if latest:
+        print(f"\ntony: updated {before or '?'} -> {latest}.")
+    else:
+        print("\ntony: the installer finished. Check it with `tony --version`.")
+    return 0

tony_cli/layout.py

@@ -0,0 +1,233 @@
+"""The deterministic layer: line numbers, spans, and tags, decided from the diff.
+
+This is the single place those decisions run. The payload carries the result,
+and every renderer — the local page and the hosted viewer are the same
+TypeScript bundle — consumes it without re-deriving anything. See DESIGN.md,
+"Ground truth": the model can name a line range, it can never supply the
+contents of one, and it never decides where a note lands.
+"""
+
+import json
+import re
+
+JSON_FENCE = re.compile(r"```json\s*\n(.*?)\n```", re.DOTALL)
+HUNK_HEADER = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@")
+
+
+def parseReview(review):
+    """Pull the JSON block out of a raw review. A malformed block yields {}."""
+    match = JSON_FENCE.search(review)
+    if not match:
+        return {}
+    try:
+        return json.loads(match.group(1))
+    except json.JSONDecodeError:
+        return {}
+
+
+def changedRuns(body):
+    """Map each contiguous run of changed lines to its new-file span.
+
+    Returns a list of (start, end, hadDeletion) in new-file line numbers.
+    Deletion-only runs collapse to a single position, since they occupy no line
+    in the new file. `hadDeletion` is what lets the page tell an insertion from a
+    replacement without taking the model's word for it.
+    """
+    runs = []
+    newLine = None
+    run = None
+
+    for line in body.split("\n"):
+        header = HUNK_HEADER.match(line)
+        if header:
+            if run:
+                runs.append(tuple(run))
+                run = None
+            newLine = int(header.group(1))
+            continue
+        if newLine is None:
+            continue
+
+        if line.startswith("+"):
+            if run:
+                run[1] = newLine
+            else:
+                run = [newLine, newLine, False]
+            newLine += 1
+        elif line.startswith("-"):
+            if run:
+                run[2] = True
+            else:
+                run = [newLine, newLine, True]
+        else:
+            if run:
+                runs.append(tuple(run))
+                run = None
+            newLine += 1
+
+    if run:
+        runs.append(tuple(run))
+    return runs
+
+
+def spanFor(anchor, runs):
+    """The changed run an annotation refers to: the one containing it, else the next."""
+    for run in runs:
+        if run[0] <= anchor <= run[1]:
+            return run
+    later = [r for r in runs if r[0] >= anchor]
+    return later[0] if later else (anchor, anchor, False)
+
+
+def kindFor(claimed, span):
+    """What the tag says, decided by the diff rather than by the model.
+
+    A model that inserts a guard ahead of existing code often calls that
+    "changed" — true of the behaviour, false of the lines, and the reader ends up
+    hunting an all-green block for the thing that was replaced. The diff already
+    knows. "removed" is left alone: those runs are deletions by definition.
+    """
+    if claimed == "removed" or not span or len(span) < 3:
+        return claimed or "changed"
+    return "changed" if span[2] else "added"
+
+
+def layout(body, items, gaps=True):
+    """One file as ordered blocks: diff rows, with notes above the line they describe.
+
+    `items` are dicts of {"k": "note"|"risk", "n": index, "data": obj}, where
+    `n` indexes back into the payload's own annotations or risks array.
+
+    Blocks are either {"k": "row", "cls", "g", "text"} or
+    {"k": "note"|"risk", "n", "span", "tag"}.
+    """
+    runs = changedRuns(body) if body else []
+
+    # Where a note lands.
+    #
+    # A note that is the only thing said about a run describes that whole run,
+    # so it belongs at the run's first line — the model naming a line partway in
+    # splits the very block it is explaining.
+    #
+    # A run with SEVERAL notes is the opposite case: an added file is one
+    # contiguous run from line 1 to its end, and the three notes inside it are
+    # describing three different parts. Snapping those together would stack them
+    # at the top and throw away the only positional information there is. So
+    # only a sole note moves.
+    resolved = []
+    perRun = {}
+    for item in items:
+        line = item["data"].get("line")
+        claimed = int(line) if isinstance(line, (int, float)) else 0
+        span = spanFor(claimed, runs) if runs else None
+        resolved.append((item, span, claimed))
+        if span in runs:
+            perRun[span] = perRun.get(span, 0) + 1
+
+    pending = {}
+    covered = set()
+    for item, span, claimed in resolved:
+        if span in runs:
+            covered.add(span)
+        alone = span in runs and perRun[span] == 1
+        pending.setdefault(span[0] if alone else claimed, []).append(("note", item, span))
+
+    # A run nothing explained. The promise is that every changed block is
+    # accounted for, and a review that quietly covers two thirds of a diff is
+    # indistinguishable from one that covers all of it — which is the failure
+    # worth making impossible to miss. The gap is placed like any other note,
+    # at the first line of the run it marks.
+    if gaps:
+        for run in runs:
+            if run not in covered:
+                pending.setdefault(run[0], []).append(("gap", None, run))
+
+    def block(entry):
+        kind, item, span = entry
+        if kind == "gap":
+            return {"k": "gap", "span": list(span), "tag": kindFor(None, span)}
+        return {
+            "k": item["k"],
+            "n": item["n"],
+            "span": list(span) if span else None,
+            "tag": kindFor(item["data"].get("kind"), span),
+        }
+
+    blocks = []
+    newLine = None
+
+    for line in body.split("\n"):
+        header = HUNK_HEADER.match(line)
+        if header:
+            newLine = int(header.group(1))
+            # anything anchored before this hunk that never matched, flush here
+            for anchor in sorted(k for k in pending if k < newLine):
+                blocks += [block(e) for e in pending.pop(anchor)]
+            blocks.append({"k": "row", "cls": "h", "g": None, "text": line})
+            continue
+
+        if newLine is not None and newLine in pending:
+            blocks += [block(e) for e in pending.pop(newLine)]
+
+        if line.startswith("+"):
+            cls, gutter = "a", newLine
+            newLine = (newLine or 0) + 1
+        elif line.startswith("-"):
+            cls, gutter = "d", None
+        else:
+            cls, gutter = "c", newLine
+            if newLine is not None:
+                newLine += 1
+
+        blocks.append({"k": "row", "cls": cls, "g": gutter, "text": line})
+
+    for anchor in sorted(pending):
+        blocks += [block(e) for e in pending.pop(anchor)]
+
+    return blocks
+
+
+# Files nobody reads and nobody should be asked to explain. Decided here, from
+# the path alone, rather than left to the model — "skip lockfiles" as a prompt
+# instruction is a judgment call, and a judgment call is what put 4000 lines of
+# package-lock.json into a coverage denominator.
+SKIP_NAMES = {
+    "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "npm-shrinkwrap.json",
+    "Cargo.lock", "poetry.lock", "Pipfile.lock", "composer.lock", "Gemfile.lock",
+    "go.sum", "flake.lock",
+}
+SKIP_SUFFIXES = (".min.js", ".min.css", ".map", ".snap", ".lock")
+
+
+def isSkippable(path):
+    """True for generated files that are not worth an annotation."""
+    name = (path or "").rsplit("/", 1)[-1]
+    return name in SKIP_NAMES or name.endswith(SKIP_SUFFIXES)
+
+
+def runCoverage(body, items):
+    """(total runs, unexplained runs) for one file.
+
+    The same resolution `layout` does, without building a page — this is what
+    lets the review loop check its own work before anyone reads it.
+    """
+    runs = changedRuns(body) if body else []
+    covered = set()
+    for item in items:
+        line = item["data"].get("line")
+        claimed = int(line) if isinstance(line, (int, float)) else 0
+        span = spanFor(claimed, runs) if runs else None
+        if span in runs:
+            covered.add(span)
+    return runs, [r for r in runs if r not in covered]
+
+
+def itemsByPath(annotations, risks):
+    """Annotations and risks grouped per file, keeping their index in the payload arrays."""
+    byPath = {}
+    for n, a in enumerate(annotations):
+        byPath.setdefault(a.get("path"), []).append({"k": "note", "n": n, "data": a})
+    for n, r in enumerate(risks):
+        if r.get("path"):
+            byPath.setdefault(r["path"], []).append({"k": "risk", "n": n, "data": r})
+    return byPath