feat: scan stem + sidecar text reader

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

gates/scan.py

@@ -36,3 +36,19 @@ def resolve_index(count, index):
     if index < 0 or index >= count:
         raise IndexError(f"index {index} out of range: {count} images")
     return index
+
+
+def stem(image_path):
+    return os.path.splitext(os.path.basename(image_path))[0]
+
+
+def sidecar_path(image_path):
+    return os.path.splitext(image_path)[0] + ".txt"
+
+
+def read_sidecar(image_path):
+    p = sidecar_path(image_path)
+    if not os.path.isfile(p):
+        return ""
+    with open(p, "r", encoding="utf-8") as f:
+        return f.read().rstrip("\n")

tests/test_scan.py

@@ -53,3 +53,18 @@ def test_resolve_index_empty_raises():
     import pytest
     with pytest.raises(FileNotFoundError):
         scan.resolve_index(0, 0)
+
+def test_stem():
+    assert scan.stem("/a/b/shot01.png") == "shot01"
+
+def test_sidecar_path():
+    assert scan.sidecar_path("/a/b/shot01.png") == "/a/b/shot01.txt"
+
+def test_read_sidecar_present(tmp_path):
+    (tmp_path / "x.png").write_bytes(b"i")
+    (tmp_path / "x.txt").write_text("a caption\n", encoding="utf-8")
+    assert scan.read_sidecar(str(tmp_path / "x.png")) == "a caption"
+
+def test_read_sidecar_missing_returns_empty(tmp_path):
+    (tmp_path / "x.png").write_bytes(b"i")
+    assert scan.read_sidecar(str(tmp_path / "x.png")) == ""