A missing LFS object looks fine from this machine

The two tester images added for the README exist here, are LFS-tracked here,
and are referenced by a correct media.githubusercontent URL -- and both return
404, because their objects have never left this disk. Nothing local says so.
The tree is right, the pointer is right, the working copy is the real PNG.

`tools/check_lfs_urls.py` fetches every image the README and the Icon/Banner
fields point at and asserts three things per URL: it comes back 200, it does
not begin with a pointer header, and it is the same byte count as the file on
disk. Status alone is not enough -- raw.githubusercontent.com serves the
pointer as `200 OK` / `text/plain`, which is the silent half of this trap and
the reason the size comparison is there. Falsified against the live server on
both branches: the two tester URLs fail on status, and a raw. URL for a file
that is otherwise fine returns 130 bytes beginning `version https://git-lfs`,
which trips the other two assertions.

It is the only checker that leaves the machine, so it stays out of
check_all.py; the docs say to run it after the push and before publishing.

CLAUDE.md also gains the ordering constraint the 404s exposed: `git lfs push
<url> <branch>` covers only the objects reachable from that branch, so a
picture added on a feature branch is not covered by a `main` push until the
merge has landed. Merge, then objects, then branch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PLXmbwfdXirQ5oFreXPcMi

CLAUDE.md

@@ -33,10 +33,17 @@ git lfs push https://github.com/dntpi/ComfyUI-Hand-Tie-Clips.git main
 git push origin main
 ```
 
-Two further traps behind that one, both silent:
+**`git lfs push <url> <branch>` uploads only the objects reachable from that
+branch**, so a picture added on a feature branch is not covered by a `main`
+push until the merge has landed locally. Merge first, then push the objects,
+then push the branch. Getting that order wrong is how two images sat on `v2`
+for a release cycle while the `main` push reported success.
+
+Three further traps behind that one, all silent:
 
 - **`raw.githubusercontent.com` does not resolve an LFS pointer.** It serves the 131-byte pointer file as `200 OK` / `text/plain`, so every `<img>` breaks with no error anywhere. Use `media.githubusercontent.com/media/<owner>/<repo>/<ref>/<path>`, which is what the README and the `Icon`/`Banner` fields point at. `github.com/<o>/<r>/raw/` behaves like `raw.`, not like `media.`.
 - **HuggingFace refuses plain binaries regardless of size** -- it rejected PNGs of 262-545 KB, not just the >10 MB the old `.gitattributes` comment assumed. Anything binary under `docs/img/` must be LFS or the mirror push fails.
+- **A missing object is not visible from this machine.** The tree, the pointer and the working copy are all correct locally whether or not the upload happened; only a fetch tells you. `tools/check_lfs_urls.py` fetches every image the README and the `Icon`/`Banner` fields reference and asserts each comes back 200, not starting with a pointer header, and the same byte count as the file on disk -- which is what catches the `raw.` case, since that one is a successful response. It is the only checker that needs the network, so it is not in `check_all.py`: run it after the push and before `comfy node publish`.
 
 ## Architecture
 

tools/check_lfs_urls.py

@@ -0,0 +1,132 @@
+"""Every image the published page and the registry listing point at, fetched.
+
+This is the one check that has to leave the machine, which is why it is not in
+check_all.py: run it after the push, before `comfy node publish`.
+
+Two failures it exists for, both silent:
+
+  1. **An LFS object that was never uploaded.** `origin` carries two push URLs
+     and git-lfs uploads to the first only, so objects can be missing on GitHub
+     while the tree that references them is not. `git lfs push <github-url>
+     <branch>` fixes it -- but only for objects reachable from THAT branch, so
+     a picture added on a feature branch needs the merge to land first. Get the
+     order wrong and the page renders a broken image with no error anywhere.
+
+  2. **A pointer served as 200 OK.** `raw.githubusercontent.com` does not
+     resolve LFS: it returns the 131-byte pointer file, as text/plain, with a
+     success status. Nothing in a browser, a linter or a link checker calls
+     that an error. Only the size gives it away.
+
+So status is not enough. Each URL must come back the same number of bytes as
+the file on disk, and must not begin with a pointer header.
+"""
+from __future__ import annotations
+
+import io
+import os
+import re
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+# The pointer file's first line. Assembled, so a hit on this file's own text
+# cannot be mistaken for the thing it looks for.
+POINTER = "version " + "https://git-lfs"
+
+MEDIA = "https://media.githubusercontent.com/media/"
+FAILS = []
+
+
+def ck(label, ok, detail=""):
+    print("  %-4s %-52s %s" % ("ok" if ok else "FAIL", label, detail))
+    if not ok:
+        FAILS.append(label)
+
+
+def urls_referenced():
+    """Every remote image the two published faces of this pack point at."""
+    out = []
+    readme = io.open(os.path.join(HERE, "README.md"), encoding="utf-8").read()
+    for m in re.finditer(r"!\[[^\]]*\]\((https?://[^)]+)\)", readme):
+        out.append(("README.md", m.group(1)))
+    toml = io.open(os.path.join(HERE, "pyproject.toml"), encoding="utf-8").read()
+    for field in ("Icon", "Banner"):
+        m = re.search(r"^%s\s*=\s*\"([^\"]+)\"" % field, toml, re.M)
+        if m:
+            out.append(("pyproject.toml %s" % field, m.group(1)))
+    return out
+
+
+def local_path(url):
+    """docs/img/x.png, out of .../media/<owner>/<repo>/<ref>/docs/img/x.png."""
+    if not url.startswith(MEDIA):
+        return None
+    rest = url[len(MEDIA):].split("/")
+    return "/".join(rest[3:]) if len(rest) > 3 else None
+
+
+def main():
+    refs = urls_referenced()
+    print("checking %d referenced image(s)\n" % len(refs))
+
+    tracked = subprocess.run(["git", "lfs", "ls-files", "-n"], cwd=HERE,
+                             capture_output=True, text=True).stdout.split("\n")
+    tracked = {p.strip() for p in tracked if p.strip()}
+
+    for where, url in refs:
+        name = url.rsplit("/", 1)[-1]
+        # The whole point of media. is that raw. lies about LFS.
+        if "raw.githubusercontent.com" in url or "/raw/" in url:
+            ck("%s: not a raw. URL" % name, False,
+               "%s -- raw. serves the pointer as 200 OK" % where)
+            continue
+
+        rel = local_path(url)
+        if rel is None:
+            ck("%s: recognised host" % name, True, "not LFS, skipped")
+            continue
+
+        disk = os.path.join(HERE, rel.replace("/", os.sep))
+        if not os.path.exists(disk):
+            ck("%s: exists in this tree" % name, False, rel)
+            continue
+        size = os.path.getsize(disk)
+
+        # An image referenced from the page but not LFS-tracked pushes fine to
+        # GitHub and is refused by the HuggingFace mirror, which takes no plain
+        # binaries at any size.
+        ck("%s: LFS-tracked" % name, rel in tracked, rel)
+
+        try:
+            with urllib.request.urlopen(url, timeout=30) as r:
+                body = r.read()
+                status = r.status
+        except urllib.error.HTTPError as e:
+            ck("%s: served" % name, False,
+               "HTTP %d -- the object is not on GitHub; `git lfs push "
+               "<github-url> <branch>` for the branch that has it" % e.code)
+            continue
+        except OSError as e:
+            ck("%s: served" % name, False, "unreachable: %s" % e)
+            continue
+
+        ck("%s: served" % name, status == 200, "HTTP %d" % status)
+        ck("%s: content, not a pointer" % name,
+           not body[:40].decode("utf-8", "replace").startswith(POINTER),
+           "%d bytes" % len(body))
+        ck("%s: matches the file on disk" % name, len(body) == size,
+           "%d served vs %d on disk" % (len(body), size))
+
+    if FAILS:
+        print("\nLFS URL CHECK: %d failure(s). The page renders these broken."
+              % len(FAILS))
+        return 1
+    print("\nLFS URL CHECK: all passed")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())