From a3134f0b168bc653b6f069f1f3910405cd3b82c0 Mon Sep 17 00:00:00 2001 From: SDNick484 Date: Tue, 10 Nov 2026 10:23:59 -0800 Subject: [PATCH] sync_shared: an optional `version` lock key, the release tag on the locked commit (F14) shared.lock may now carry `version = "v0.1.0"` next to `commit`. It is a label for people; the SHA stays the pin. - --update looks up the release tags on the commit it moves to (one call to GitHub's tags endpoint, first 100) and writes the highest (vX.Y.Z[-pre]; a release beats its own -rcN), or leaves the key out when the commit is untagged. Tagging the locked commit later is picked up by the next --update ("already at 1a2b3c4 (v0.1.0)"). A failed lookup warns and doesn't fail the update: same commit keeps its version, a new commit gets none. - read_lock knows the key (no unknown-key warning) and refuses anything that isn't a strict vX.Y.Z[-pre]: the value goes back into TOML as written. - --check's label and --update's message show it; so does the COMMIT column of sync_all_siblings.py status. Rollout: siblings run their own copy of this script, and --update writes the lock with the copy that is running, i.e. the one from before the update. So the sync that delivers this script still writes a lock without `version`; the key first appears on the following --update, written and then read by a script that knows it. An older script only ever sees it if a lock is copied or downgraded by hand, and then it warns and ignores the key. Rollback: delete the line. Refs #16 Co-Authored-By: Claude Opus 5.5 --- README.md | 7 +++ scripts/sync_all_siblings.py | 7 ++- scripts/sync_shared.py | 77 +++++++++++++++++++++++++---- tests/test_sync_all_siblings.py | 14 ++++++ tests/test_sync_shared.py | 87 ++++++++++++++++++++++++++++++++- 5 files changed, 179 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index ce99cc3..f814627 100644 --- a/README.md +++ b/README.md @@ -43,10 +43,17 @@ Each sibling carries one small file, `shared.lock`, plus the copies themselves: # shared.lock, in a sibling repo = "SDNick484/mcp-server-shared" commit = "73e65ec9e63c8c3a1b3831697da56c5b86854a5c" # a commit on this repo's main +version = "v0.1.0" # written by --update: the tag on that commit, if any package = "webos_mcp" # what replaces __PKG__ exclude = ["registry"] # optional: modules this sibling doesn't take ``` +`version` is a label for people (`--check` and `sync_all_siblings.py status` show it); the +`commit` is still the pin. `--update` writes the release tag (`vX.Y.Z[-pre]`) pointing at the +commit it moves to, and leaves the key out when that commit is untagged. A script from before +`version` existed warns that it doesn't know the key and otherwise ignores it; deleting the line +is always safe. + Running the sync script in a sibling: ```sh diff --git a/scripts/sync_all_siblings.py b/scripts/sync_all_siblings.py index 89d7965..ab1dd41 100644 --- a/scripts/sync_all_siblings.py +++ b/scripts/sync_all_siblings.py @@ -73,6 +73,7 @@ class SiblingInfo: package: str commit: str repo: str = f"{OWNER}/{SHARED_REPO_NAME}" + version: str | None = None # shared.lock's optional release tag @property def name(self) -> str: @@ -133,11 +134,13 @@ def read_sibling_info(sibling: Path) -> SiblingInfo: package = str(data.get("package") or "?") commit = str(data.get("commit") or "?") repo = str(data.get("repo") or f"{OWNER}/{SHARED_REPO_NAME}") + version = str(data["version"]) if data.get("version") else None except (OSError, tomllib.TOMLDecodeError): package = "?" commit = "invalid" repo = f"{OWNER}/{SHARED_REPO_NAME}" - return SiblingInfo(path=sibling, package=package, commit=commit, repo=repo) + version = None + return SiblingInfo(path=sibling, package=package, commit=commit, repo=repo, version=version) def _run_cmd(cmd: Sequence[str], *, cwd: Path) -> subprocess.CompletedProcess[str]: @@ -264,7 +267,7 @@ def run_status(parent_dir: Path, *, latest: bool = False, only: str | None = Non StatusRow( sibling=info.name, package=info.package, - commit=info.short_commit, + commit=f"{info.short_commit} {info.version}" if info.version else info.short_commit, status=status, ok=ok, ) diff --git a/scripts/sync_shared.py b/scripts/sync_shared.py index d4e78c5..05786cd 100644 --- a/scripts/sync_shared.py +++ b/scripts/sync_shared.py @@ -96,12 +96,17 @@ _SHA = re.compile(r"[0-9a-f]{40}") _REPO = re.compile(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+") _PACKAGE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*") +# A release tag of mcp-server-shared, as the lock's `version` carries it: v0.1.0, v1.2.0-rc1. Strict +# on purpose: it is written into the lock's TOML as is, and anything else on a commit (a +# moving tag, a typo) isn't a version. +_VERSION = re.compile(r"v(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.]+))?") LOCK_HEADER = """\ # Which mcp-server-shared commit this repo's shared files come from, and this # repo's package name (it replaces __PKG__). Written by -# `python scripts/sync_shared.py --update`; see that script. An optional -# `exclude = ["remote"]` names shared modules this repo doesn't take. +# `python scripts/sync_shared.py --update`; see that script. `version`, when +# present, is the tag on that commit: a label only, the commit is the pin. An +# optional `exclude = ["remote"]` names shared modules this repo doesn't take. """ @@ -116,8 +121,11 @@ class Lock: commit: str package: str exclude: tuple[str, ...] = () # shared modules this repo doesn't take + version: str | None = None # the release tag on `commit`, if it has one (written by --update) - KEYS = ("repo", "commit", "package", "exclude") # what read_lock understands; anything else is a typo + # What read_lock understands; anything else is a typo. "version" was added after "exclude": a + # script from before it warns about the key and otherwise ignores it. + KEYS = ("repo", "commit", "version", "package", "exclude") def validate(self) -> Lock: # The regex allows "." and "-" (real repo names have them), but a segment that *is* "." or ".." @@ -131,10 +139,20 @@ def validate(self) -> Lock: for name in self.exclude: if not _PACKAGE.fullmatch(name): raise SyncError(f'{LOCK}: exclude must list module names like "remote" (got {name!r})') + if self.version is not None and not _VERSION.fullmatch(self.version): + raise SyncError(f'{LOCK}: version must be a tag like "v0.1.0" (got {self.version!r})') return self + @property + def at(self) -> str: + """For messages: "1a2b3c4" or "1a2b3c4 (v0.1.0)".""" + return _at(self.commit, self.version) + def dump(self) -> str: - text = f'{LOCK_HEADER}repo = "{self.repo}"\ncommit = "{self.commit}"\npackage = "{self.package}"\n' + text = f'{LOCK_HEADER}repo = "{self.repo}"\ncommit = "{self.commit}"\n' + if self.version: + text += f'version = "{self.version}"\n' + text += f'package = "{self.package}"\n' if self.exclude: text += "exclude = [" + ", ".join(f'"{name}"' for name in self.exclude) + "]\n" return text @@ -160,12 +178,16 @@ def read_lock(root: Path) -> Lock: exclude = data.get("exclude", []) if not isinstance(exclude, list) or not all(isinstance(name, str) for name in exclude): raise SyncError(f'{LOCK}: exclude must be a list of module names, like ["remote"] (got {exclude!r})') + version = data.get("version") + if version is not None and not isinstance(version, str): + raise SyncError(f'{LOCK}: version must be a tag like "v0.1.0" (got {version!r})') try: lock = Lock( str(data.get("repo", DEFAULT_REPO)), str(data["commit"]), str(data["package"]), tuple(dict.fromkeys(exclude)), # drop repeats, keep the order written + version, ) except KeyError as exc: raise SyncError(f"{LOCK} is missing {exc.args[0]!r}") from None @@ -263,6 +285,33 @@ def lock_is_on_main(repo: str, commit: str) -> str | None: return f"couldn't check whether the locked commit is on main (unexpected compare status {status!r})" +def _at(commit: str, version: str | None) -> str: + return f"{commit[:7]} ({version})" if version else commit[:7] + + +def version_tag(repo: str, commit: str) -> str | None: + """The release tag on `commit` (the highest, if several), or None when it has none. + + One call to GitHub's tags endpoint, first page of 100: plenty for this repo's release cadence. + Raises SyncError when GitHub can't be asked; the caller decides what that means. + """ + url = f"https://api.github.com/repos/{repo}/tags?per_page=100" + try: + data = json.loads(_get(url, "application/vnd.github+json")) + except ValueError: + raise SyncError("GitHub's tag list isn't JSON") from None + tags = data if isinstance(data, list) else [] + names = [ + tag.get("name") + for tag in tags + if isinstance(tag, dict) and isinstance(tag.get("commit"), dict) and tag["commit"].get("sha") == commit + ] + versions = [m for name in names if isinstance(name, str) and (m := _VERSION.fullmatch(name))] + # Highest first by number; a release sorts after its own pre-releases (v1.0.0 > v1.0.0-rc1). + best = max(versions, key=lambda m: (int(m[1]), int(m[2]), int(m[3]), m[4] is None, m[4] or ""), default=None) + return best[0] if best else None + + def _warn_if_lock_is_off_main(lock: Lock) -> None: reason = lock_is_on_main(lock.repo, lock.commit) if reason: @@ -274,10 +323,12 @@ class GitHub: repo: str commit: str why: str # "locked" or "main" + version: str | None = None # the lock's version, for the label @property def label(self) -> str: - return f"{self.repo.split('/')[-1]} at {self.commit[:7]} ({self.why})" + version = f" {self.version}" if self.version else "" + return f"{self.repo.split('/')[-1]} at {self.commit[:7]}{version} ({self.why})" def read(self, path: str) -> bytes: return _get(f"https://raw.githubusercontent.com/{self.repo}/{self.commit}/{path}") @@ -648,7 +699,7 @@ def run(args: argparse.Namespace) -> int: print(f"(shared.lock is at {lock.commit[:7]}, main at {main[:7]}, with no shared file changed)") _report_orphans(root, package, files, exclude) return status - source = GitHub(lock.repo, lock.commit, "locked") + source = GitHub(lock.repo, lock.commit, "locked", lock.version) files = wanted_files(source, package, writing=False, root=root, exclude=exclude) status = report(root, files, source.label + _excluding(exclude), "python scripts/sync_shared.py") _report_orphans(root, package, files, exclude) @@ -660,16 +711,24 @@ def run(args: argparse.Namespace) -> int: source = GitHub(lock.repo, main, "main") files = wanted_files(source, package, writing=not dry_run, root=root, exclude=exclude) changed = write_files(root, files, dry_run=dry_run, force=force) - new_lock = Lock(lock.repo, main, lock.package, lock.exclude) # exclude carries over unchanged + try: + version = version_tag(lock.repo, main) + except SyncError as exc: + # The version is a label; the SHA is the pin. Keep the label it had if the commit didn't + # move, else write none rather than guess. + version = lock.version if main == lock.commit else None + kept = f"keeping {version}" if version else "writing none" + print(f"sync_shared.py: warning: couldn't look up a version tag ({exc}); {kept}", file=sys.stderr) + new_lock = Lock(lock.repo, main, lock.package, lock.exclude, version) # exclude carries over unchanged if new_lock != lock and not dry_run: write_atomic(root / LOCK, new_lock.dump().encode("utf-8")) # last: only once every file is in - moved = f"{lock.commit[:7]} -> {main[:7]}" if main != lock.commit else f"already at {main[:7]}" + moved = f"{lock.at} -> {new_lock.at}" if main != lock.commit else f"already at {new_lock.at}" prefix = "dry run, shared.lock" if dry_run else "shared.lock" print(f"{prefix}: {moved}{_excluding(exclude)}; " + (", ".join(changed) if changed else "no files changed")) _report_orphans(root, package, files, exclude) return 1 if (dry_run and (changed or new_lock != lock)) else 0 - source = GitHub(lock.repo, lock.commit, "locked") + source = GitHub(lock.repo, lock.commit, "locked", lock.version) files = wanted_files(source, package, writing=not dry_run, root=root, exclude=exclude) changed = write_files(root, files, dry_run=dry_run, force=force) label = source.label + _excluding(exclude) diff --git a/tests/test_sync_all_siblings.py b/tests/test_sync_all_siblings.py index 2057e98..96aecce 100644 --- a/tests/test_sync_all_siblings.py +++ b/tests/test_sync_all_siblings.py @@ -126,6 +126,20 @@ def fake_run_cmd_drift(cmd: Sequence[str], *, cwd: Path) -> subprocess.Completed assert all("--check" in cmd and "--latest" in cmd for _, cmd in recorded) +def test_status_shows_the_locks_version_next_to_the_commit(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys): + mod = load_script() + tagged = make_sibling(tmp_path, "mcp-server-alpha", "alpha_mcp", COMMIT_A) + with (tagged / "shared.lock").open("a", encoding="utf-8") as lock: + lock.write('version = "v0.1.0"\n') + make_sibling(tmp_path, "mcp-server-beta", "beta_mcp", COMMIT_B) + ok = subprocess.CompletedProcess([], 0, stdout="", stderr="") + monkeypatch.setattr(mod, "_run_cmd", lambda cmd, *, cwd: ok) + assert mod.main(["status", "--parent-dir", str(tmp_path)]) == 0 + rows = {line.split()[0]: line for line in capsys.readouterr().out.splitlines()[2:]} + assert f"{COMMIT_A[:7]} v0.1.0" in rows["mcp-server-alpha"] + assert "v0." not in rows["mcp-server-beta"] + + def test_status_reports_error_on_invalid_lock(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys): mod = load_script() bad = tmp_path / "mcp-server-broken" diff --git a/tests/test_sync_shared.py b/tests/test_sync_shared.py index 4f1dddc..6bf9ade 100644 --- a/tests/test_sync_shared.py +++ b/tests/test_sync_shared.py @@ -7,6 +7,7 @@ from __future__ import annotations import importlib.util +import json import subprocess import sys from pathlib import Path @@ -76,13 +77,19 @@ def github(monkeypatch): commits = {OLD: snapshot("1"), NEW: snapshot("2")} # main's history is OLD -> NEW. `compare` answers how a commit relates to main, like GitHub's # endpoint; "history" is the SHAs on main, "on_main_check" counts those calls. - state = {"main": NEW, "requests": 0, "history": [OLD, NEW], "on_main_check": 0} + # "tags" is name -> SHA, served like GitHub's /tags endpoint (untagged unless a test adds some). + state = {"main": NEW, "requests": 0, "history": [OLD, NEW], "on_main_check": 0, "tags": {}} def fake_get(url: str, accept: str | None = None) -> bytes: state["requests"] += 1 if url.endswith("/commits/main"): assert accept == "application/vnd.github.sha" return str(state["main"]).encode() + if "/tags?" in url: + if state["tags"] is None: + raise sync.SyncError(f"GET {url}: HTTP 403 Forbidden (rate limited? set GITHUB_TOKEN)") + tags = dict(state["tags"]) + return json.dumps([{"name": name, "commit": {"sha": sha}} for name, sha in tags.items()]).encode() if "/compare/main..." in url: state["on_main_check"] += 1 sha = url.rsplit("...", 1)[1] @@ -661,7 +668,7 @@ def test_unknown_lock_keys_are_warned_about(github, sibling, capsys): assert run(sync, sibling) == 0 err = capsys.readouterr().err assert "shared.lock has keys this script doesn't use: excludes" in err - assert "it reads repo, commit, package, exclude" in err + assert "it reads repo, commit, version, package, exclude" in err assert (sibling / "src/demo_mcp/extra.py").exists() # the typo didn't exclude anything, as warned @@ -788,3 +795,79 @@ def test_force_with_a_non_writing_mode_is_refused(github, sibling, args): sync, _, _ = github with pytest.raises(SystemExit): run(sync, sibling, *args) + + +# --- version tags ---------------------------------------------------------------------------------- +def test_update_records_the_tag_on_main_and_check_shows_it(github, sibling, capsys): + sync, _, state = github + state["tags"] = {"v0.1.0": NEW, "v0.0.9": OLD, "not-a-version": NEW} + assert run(sync, sibling, "--update") == 0 + lock = (sibling / "shared.lock").read_text() + assert f'commit = "{NEW}"\nversion = "v0.1.0"\n' in lock + assert f"shared.lock: {OLD[:7]} -> {NEW[:7]} (v0.1.0);" in capsys.readouterr().out + assert run(sync, sibling, "--check") == 0 + assert f"all 3 match mcp-server-shared at {NEW[:7]} v0.1.0 (locked)" in capsys.readouterr().out + + +def test_an_untagged_main_writes_no_version_and_drops_a_stale_one(github, sibling): + sync, _, state = github + (sibling / "shared.lock").write_text( + f'repo = "SDNick484/mcp-server-shared"\ncommit = "{OLD}"\nversion = "v0.0.9"\npackage = "demo_mcp"\n' + ) + assert run(sync, sibling, "--update") == 0 + lock = (sibling / "shared.lock").read_text() + assert "version" not in lock.replace("# ", "").split("repo =", 1)[1] # the header may mention it + + +def test_tagging_the_locked_commit_later_is_picked_up_by_update(github, sibling, capsys): + sync, _, state = github + run(sync, sibling, "--update") + state["tags"] = {"v0.1.0": NEW} + assert run(sync, sibling, "--update") == 0 + assert f"shared.lock: already at {NEW[:7]} (v0.1.0)" in capsys.readouterr().out + assert 'version = "v0.1.0"' in (sibling / "shared.lock").read_text() + + +def test_of_two_tags_on_one_commit_the_highest_release_wins(github, sibling): + sync, _, state = github + state["tags"] = {"v1.2.0-rc1": NEW, "v1.10.0": NEW, "v1.9.0": NEW, "v1.10.0-rc2": NEW} + run(sync, sibling, "--update") + assert 'version = "v1.10.0"' in (sibling / "shared.lock").read_text() + + +def test_a_failed_tag_lookup_warns_and_keeps_what_it_can(github, sibling, capsys): + sync, _, state = github + state["tags"] = {"v0.1.0": NEW} + run(sync, sibling, "--update") + state["tags"] = None # rate limited from here on + assert run(sync, sibling, "--update") == 0 # same commit: the version it had is kept + assert 'version = "v0.1.0"' in (sibling / "shared.lock").read_text() + assert "couldn't look up a version tag" in capsys.readouterr().err + state["main"] = OLD # a different commit: its tag is unknown, so none is written + state["history"] = [NEW, OLD] + assert run(sync, sibling, "--update") == 0 + assert "version" not in (sibling / "shared.lock").read_text().split("repo =", 1)[1] + + +def test_a_lock_with_version_round_trips_and_a_bad_one_is_refused(github, sibling, capsys): + sync, _, _ = github + text = f'repo = "SDNick484/mcp-server-shared"\ncommit = "{OLD}"\nversion = "v0.1.0"\npackage = "demo_mcp"\n' + (sibling / "shared.lock").write_text(text) + lock = sync.read_lock(sibling) + assert lock.version == "v0.1.0" + (sibling / "shared.lock").write_text(lock.dump()) + assert sync.read_lock(sibling) == lock + assert "doesn't use" not in capsys.readouterr().err # a known key: no warning + for bad in ['"0.1.0"', '"v1\\" injected = \\"x"', "1"]: + (sibling / "shared.lock").write_text(text.replace('"v0.1.0"', bad)) + assert run(sync, sibling, "--check") == 2 + assert "version must be a tag like" in capsys.readouterr().err + + +def test_version_tag_handles_odd_answers(github, monkeypatch): + sync, _, _ = github + monkeypatch.setattr(sync, "_get", lambda url, accept=None: b"") + with pytest.raises(sync.SyncError, match="isn't JSON"): + sync.version_tag("SDNick484/mcp-server-shared", NEW) + monkeypatch.setattr(sync, "_get", lambda url, accept=None: b'{"message": "Not Found"}') + assert sync.version_tag("SDNick484/mcp-server-shared", NEW) is None