contrib/vendor-check: watching upstream is one command now

Vendoring by pinned commit stays (D12) -- the package channels build
from source archives where submodules are empty, the arch build is
offline-clean because the core is in the tarball, and upstream has no
stable release channel to depend on anyway. What was missing is the
watching: vendor-check reads the pin from vendor.json, asks the
GitHub API what happened since, and lists the commits touching the
terminal core. First run found 120 relevant commits in three weeks,
including upstream fixing the same class of kitty-graphics bug our
patch 0001 fixes -- which is the argument for finally sending it.

3 files changed, 72 insertions, 0 deletions

diff --git a/contrib/ship b/contrib/ship
index 9069481..666cb94 100755
--- a/contrib/ship
+++ b/contrib/ship
@@ -218,3 +218,4 @@ say "brew     brew tap sl0p-foo/slosh && brew install slosh"
 say "arch     $ARCH_URL (x86_64 + aarch64)"
 say "reminder: brew install --build-from-source contrib/homebrew/slosh.rb on a"
 say "          machine with brew, to prove the formula before announcing"
+say "          contrib/vendor-check: is the vendored terminal core falling behind?"
diff --git a/contrib/vendor-check b/contrib/vendor-check
new file mode 100755
index 0000000..800fa4e
--- /dev/null
+++ b/contrib/vendor-check
@@ -0,0 +1,66 @@
+#!/bin/sh
+# vendor-check -- how far behind upstream the vendored libghostty-vt is.
+#
+#   contrib/vendor-check            # summary + the commits that matter
+#   contrib/vendor-check -q         # one line, for scripts and reminders
+#
+# Vendoring is pinned by commit on purpose (D12): upstream has no stable
+# release channel for the lib, so the pin moves when we move it. This is the
+# tool that makes "keeping an eye on upstream" one command instead of a
+# browser tab: it reads the pin from vendor/libghostty-vt.vendor.json, asks
+# the GitHub API what has happened since, and shows the commits touching the
+# parts we actually ship -- the terminal core, not ghostty's app shell.
+#
+# Read-only, no working-tree changes. Re-vendoring itself stays the
+# documented manual process (vendor/patches/README.md): drop in the new
+# tree, re-apply the patches, run make test.
+set -eu
+
+UPSTREAM="${SLOSH_VT_UPSTREAM:-ghostty-org/ghostty}"
+# What the vendored build actually compiles: the VT core and the lib entry
+# points. Churn in ghostty's app, GUI and packaging is noise to us.
+PATHS="${SLOSH_VT_PATHS:-src/terminal src/lib include}"
+VJ="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)/vendor/libghostty-vt.vendor.json"
+
+fail() { printf 'vendor-check: %s\n' "$*" >&2; exit 1; }
+
+quiet=0
+[ "${1:-}" = "-q" ] && quiet=1
+
+[ -f "$VJ" ] || fail "no $VJ"
+command -v gh >/dev/null 2>&1 || fail "needs gh (for the GitHub API)"
+
+pin="$(sed -n 's/.*"source_commit": "\([a-f0-9]*\)".*/\1/p' "$VJ")"
+date="$(sed -n 's/.*"source_date": "\([^"]*\)".*/\1/p' "$VJ")"
+npatch="$(grep -c 'patches/' "$VJ" || true)"
+[ -n "$pin" ] || fail "no source_commit in $VJ"
+
+total="$(gh api "repos/$UPSTREAM/compare/$pin...HEAD" --jq .total_commits)" \
+    || fail "compare failed -- is the pin still reachable upstream?"
+
+# Per relevant path: commits since the snapshot date. Date rather than commit
+# because a path-filtered listing may never contain the pin itself; the hour
+# of slack this costs is nothing to a watch tool. The + in a timezone must
+# not reach the URL as a space.
+since="$(printf '%s' "$date" | sed 's/+/%2B/')"
+tmp="$(mktemp)"
+trap 'rm -f "$tmp"' EXIT INT TERM
+for p in $PATHS; do
+    gh api "repos/$UPSTREAM/commits?sha=HEAD&path=$p&since=$since&per_page=100" \
+        --jq '.[] | .sha[0:9] + " " + (.commit.message | split("\n")[0])' \
+        2>/dev/null || true
+done | sort -u > "$tmp"
+relevant="$(wc -l < "$tmp" | tr -d ' ')"
+
+if [ "$quiet" = 1 ]; then
+    printf 'libghostty-vt: %s commits behind %s, %s touching the VT core (pinned %.7s, %s)\n' \
+        "$total" "$UPSTREAM" "$relevant" "$pin" "${date%%T*}"
+    exit 0
+fi
+
+printf 'vendored   %.7s (%s), %s local patch(es)\n' "$pin" "${date%%T*}" "$npatch"
+printf 'upstream   %s is %s commits ahead\n' "$UPSTREAM" "$total"
+printf 'relevant   %s commits touch %s:\n\n' "$relevant" "$(echo $PATHS | tr ' ' ',')"
+head -25 "$tmp" | sed 's/^/  /'
+[ "$relevant" -gt 25 ] && printf '  ... and %s more\n' "$((relevant - 25))"
+printf '\nre-vendoring is documented in vendor/patches/README.md\n'
diff --git a/vendor/patches/README.md b/vendor/patches/README.md
index bb97cc2..893cbc4 100644
--- a/vendor/patches/README.md
+++ b/vendor/patches/README.md
@@ -12,6 +12,11 @@ lists them under `patches`.
 Re-vendoring is therefore: drop in the new upstream tree, apply each patch in
 order, resolve anything that has moved, rebuild, run `make test`.
 
+`contrib/vendor-check` says when that is worth doing: it compares the pin in
+`vendor/*.vendor.json` against upstream and lists the commits touching the
+terminal core, so watching upstream is one command rather than a browser tab.
+`ship` mentions it after every release.
+
 ## 0001 — keep kitty images across a screen clear
 
 `Terminal.eraseDisplay` called `kitty_images.delete(..., .{ .all = true })`