Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 5 additions & 2 deletions scripts/sync_all_siblings.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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]:
Expand Down Expand Up @@ -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,
)
Expand Down
77 changes: 68 additions & 9 deletions scripts/sync_shared.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
"""


Expand All @@ -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 ".."
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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}")
Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand Down
14 changes: 14 additions & 0 deletions tests/test_sync_all_siblings.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
87 changes: 85 additions & 2 deletions tests/test_sync_shared.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
from __future__ import annotations

import importlib.util
import json
import subprocess
import sys
from pathlib import Path
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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


Expand Down Expand Up @@ -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"<html>")
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
Loading