mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
5383c6bf2f
## Description
The 0.33.0 release PR (#2339) has sat in `changes-requested` since
2026-07-17. Root cause: **release-please only rewrites `pyproject.toml`
and its configured `extra-files`**, but other tracked files also carry
the version — and `server.json` is asserted byte-for-byte against
`render_server_json()`, which derives its version from `pyproject.toml`.
So the bump alone fails
`tests/test_mcp_registry/test_server_json.py::test_root_server_json_matches_builder`
(the `test (2)` shard) on every regenerated release PR.
Nothing in the repo regenerated `server.json` at all, so it fell behind
every release.
Unblocks #2339.
### Why the release *build* passes but the release PR does not
`release.yml` already runs `scripts/version-sync.py` immediately before
its own `verify-versions.py` gate (lines 145 and 278). That is why
`build` and `build-wheels` are green on #2339 despite the drift — it
syncs in the workspace, uncommitted. The regular CI test job does
**not** sync, so the fix has to be committed to the branch.
This also explains why reviewers kept seeing `verify-versions.py` fail
locally while CI's build jobs passed: the verifier is never run
un-synced inside `release.yml`.
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- **`scripts/version-sync.py`**: also write `server.json`. It was the
one version-carrying file with no writer anywhere. Values are rewritten
in place so key order and formatting keep matching the builder's
byte-for-byte output (verified: the file is pure ASCII and round-trips
exactly through `json.dumps(..., indent=2) + "\n"`).
- **`.github/workflows/release-metadata-sync.yml`** (new): on a push to
`release-please--branches--**`, run version-sync → gate on
verify-versions → commit if changed.
- **Keyed off the branch push** because release-please force-regenerates
that branch on every merge to main. That is precisely what wiped the
hand-pushed metadata fixes on #2339 (`2a86c8ff`, `d5ea4dc5`) — a push
trigger re-heals after every regeneration instead of being lost.
- **Uses the same PAT as `release-please.yml`**: a `GITHUB_TOKEN` push
does not trigger workflows, so the release PR's checks would never
re-run against the synced commit and would stay red.
- **Idempotent**: the self-triggered rerun finds no diff and exits
before pushing, so the loop terminates after one no-op run.
- **Corrected pre-existing drift on `main`**: the agent-hooks plugin
manifests, both marketplace manifests, and `.releasemetadata` were
stranded at **0.31.0** — never bumped for 0.32.0 either.
`verify-versions.py` now passes on `main`.
### Why not more `extra-files` entries
That would need ~13 jsonpath entries restating what `version-sync.py`
already knows, and a jsonpath that fails to match **fails silently** —
the same class of failure this PR removes, discoverable only after a
real release PR regenerates. There is also no precedent for nested
jsonpath (`$.packages[0].version`, `$.metadata.version`) in the config
today; both existing entries are plain `$.version`. Running the script
keeps one source of truth, and files added to it later are covered with
no change here.
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`) — no `headroom/` sources
touched
- [x] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
$ python -m pytest scripts/tests/ tests/test_release_workflows.py tests/test_mcp_registry/ -q
207 passed in 2.69s
$ ruff check scripts/version-sync.py scripts/tests/test_version_sync.py tests/test_release_workflows.py
All checks passed!
$ ruff format --check <same>
3 files already formatted
$ actionlint .github/workflows/release-metadata-sync.yml
(clean)
```
New tests:
- `test_server_json_version_is_synchronized` — version-sync moves both
`server.json` version fields and preserves the other keys.
- `test_release_metadata_sync_runs_on_release_please_branch` — asserts
the trigger, the sync→verify→commit ordering, the no-op guard, and the
PAT.
- `test_version_sync_covers_every_file_the_verifier_gates` — guards
`version-sync.py` and `verify-versions.py` against drifting apart again,
which is the root cause here.
## Real Behavior Proof
- **Environment:** macOS (Darwin arm64), Python 3.12, repo venv.
- **Exact command / steps:** reproduced the CI failure locally by
simulating release-please's partial bump, then applying the fix.
**Reproducing the exact `test (2)` failure** — set `pyproject` to 0.33.0
while `server.json` stays at 0.32.0, as release-please leaves it:
```text
$ python -m pytest tests/test_mcp_registry/test_server_json.py -q
FAILED tests/test_mcp_registry/test_server_json.py::test_root_server_json_matches_builder
1 failed, 3 passed
```
**After `version-sync.py`:**
```text
$ python scripts/version-sync.py && python -m pytest tests/test_mcp_registry/test_server_json.py -q
4 passed
```
**Both gates green on a simulated 0.33.0 bump:**
```text
$ python scripts/version-sync.py --version 0.33.0
Version synchronized to 0.33.0
$ python scripts/verify-versions.py
All versions aligned at 0.33.0
$ python -m pytest tests/test_mcp_registry/test_server_json.py -q
4 passed
```
**Idempotency** (the property the workflow's loop-termination relies
on): re-running against an already-synced tree leaves `pyproject.toml`,
`server.json`, `openclaw`, and `sdk/typescript` untouched.
- **Not tested:** the workflow has not executed on a real release-please
branch regeneration — that can only be exercised once this is on `main`
and release-please next updates #2339. The PAT push path and the
self-trigger no-op are reasoned from `release-please.yml`'s existing
token comment and from local idempotency, not observed in CI.
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`
## Additional Notes
**Context on the v0.32.0 release failure, since it is easy to misread as
"images never build".** Every artifact built for v0.32.0 — all 5 wheel
platforms including Windows, all 16 Docker builds + 8 manifests +
`promote-latest`, npm, and GitHub Packages. Only `publish-pypi` failed
(PyPI attestations, already fixed by `f9cbdd6e` / #2405), and
`create-release` was skipped because it depends on it. That is why the
release looked like it produced nothing.
**Separate, approaching blocker — not addressed here.** PyPI is at
**9.69 GB of its 10 GB project cap (96.9%)**, leaving ~305 MB against
~68 MB per release, so roughly 4 more releases fit. The `0.21.x` series
alone holds **6.58 GB across 31 releases**, from the old
every-push-is-a-release era; pruning it would reclaim two thirds of the
quota. Worth a separate issue.
**`.releasemetadata` is written but never read** by anything outside
`version-sync.py` and its test. It is kept in sync here for internal
consistency, but it may be a deletion candidate.
364 lines
13 KiB
Python
364 lines
13 KiB
Python
"""Tests for version-sync.py."""
|
|
|
|
import json
|
|
import subprocess
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
import pytest
|
|
|
|
|
|
@pytest.fixture
|
|
def temp_project(tmp_path: Path) -> dict[str, Path]:
|
|
"""Create a temporary project with all versioned files."""
|
|
# Create directory structure
|
|
root = tmp_path / "project"
|
|
headroom = root / "headroom"
|
|
headroom.mkdir(parents=True)
|
|
repo_claude_plugin = root / ".claude-plugin"
|
|
repo_claude_plugin.mkdir(parents=True)
|
|
repo_github_plugin = root / ".github" / "plugin"
|
|
repo_github_plugin.mkdir(parents=True)
|
|
plugins = root / "plugins"
|
|
openclaw = plugins / "openclaw"
|
|
openclaw.mkdir(parents=True)
|
|
agent_hooks_claude = plugins / "headroom-agent-hooks" / ".claude-plugin"
|
|
agent_hooks_claude.mkdir(parents=True)
|
|
agent_hooks_github = plugins / "headroom-agent-hooks" / ".github" / "plugin"
|
|
agent_hooks_github.mkdir(parents=True)
|
|
sdk = root / "sdk"
|
|
typescript = sdk / "typescript"
|
|
typescript.mkdir(parents=True)
|
|
|
|
# pyproject.toml
|
|
pyproject = root / "pyproject.toml"
|
|
pyproject.write_text('[project]\nversion = "0.5.25"\n')
|
|
|
|
# headroom/_version.py is runtime-derived and must not be rewritten by version-sync.
|
|
version_py = headroom / "_version.py"
|
|
version_py.write_text('"""Package version metadata."""\n\n__version__ = "0.5.25"\n')
|
|
|
|
# plugins/openclaw/package.json
|
|
openclaw_pkg = openclaw / "package.json"
|
|
openclaw_pkg.write_text(
|
|
json.dumps(
|
|
{
|
|
"name": "test",
|
|
"version": "0.5.25",
|
|
"dependencies": {"headroom-ai": "^0.22.3"},
|
|
}
|
|
)
|
|
)
|
|
|
|
repo_claude_marketplace = repo_claude_plugin / "marketplace.json"
|
|
repo_claude_marketplace.write_text(
|
|
json.dumps(
|
|
{
|
|
"metadata": {"name": "claude-marketplace", "version": "0.1.0"},
|
|
"plugins": [{"name": "headroom-agent-hooks", "version": "0.1.0"}],
|
|
}
|
|
)
|
|
)
|
|
|
|
repo_github_marketplace = repo_github_plugin / "marketplace.json"
|
|
repo_github_marketplace.write_text(
|
|
json.dumps(
|
|
{
|
|
"metadata": {"name": "copilot-marketplace", "version": "0.1.0"},
|
|
"plugins": [{"name": "headroom-agent-hooks", "version": "0.1.0"}],
|
|
}
|
|
)
|
|
)
|
|
|
|
claude_plugin = agent_hooks_claude / "plugin.json"
|
|
claude_plugin.write_text(json.dumps({"name": "headroom-agent-hooks", "version": "0.1.0"}))
|
|
|
|
github_plugin = agent_hooks_github / "plugin.json"
|
|
github_plugin.write_text(json.dumps({"name": "headroom-agent-hooks", "version": "0.1.0"}))
|
|
|
|
# sdk/typescript/package.json
|
|
typescript_pkg = typescript / "package.json"
|
|
typescript_pkg.write_text(json.dumps({"name": "test", "version": "0.5.25"}))
|
|
|
|
# server.json — the MCP registry descriptor. Asserted byte-for-byte against
|
|
# render_server_json(), which reads the version from pyproject.toml, so it has
|
|
# to move with every bump or the release PR's test job fails.
|
|
server_json = root / "server.json"
|
|
server_json.write_text(
|
|
json.dumps(
|
|
{
|
|
"name": "io.github.headroomlabs-ai/headroom",
|
|
"version": "0.5.25",
|
|
"packages": [{"registryType": "pypi", "version": "0.5.25"}],
|
|
}
|
|
)
|
|
)
|
|
|
|
return {
|
|
"root": root,
|
|
"pyproject": pyproject,
|
|
"version_py": version_py,
|
|
"openclaw_pkg": openclaw_pkg,
|
|
"repo_claude_marketplace": repo_claude_marketplace,
|
|
"repo_github_marketplace": repo_github_marketplace,
|
|
"claude_plugin": claude_plugin,
|
|
"github_plugin": github_plugin,
|
|
"typescript_pkg": typescript_pkg,
|
|
"server_json": server_json,
|
|
}
|
|
|
|
|
|
def test_version_sync_explicit_version(temp_project: dict[str, Path]) -> None:
|
|
"""Test --version flag updates all files."""
|
|
root = temp_project["root"]
|
|
script = Path(__file__).parent.parent / "version-sync.py"
|
|
|
|
result = subprocess.run(
|
|
[sys.executable, str(script), "--root", str(root), "--version", "0.7.0"],
|
|
capture_output=True,
|
|
text=True,
|
|
)
|
|
|
|
assert result.returncode == 0, f"Script failed: {result.stderr}"
|
|
|
|
# Verify pyproject.toml
|
|
pyproject_content = temp_project["pyproject"].read_text()
|
|
assert 'version = "0.7.0"' in pyproject_content
|
|
|
|
# Verify headroom/_version.py is not a synced manifest.
|
|
version_py_content = temp_project["version_py"].read_text()
|
|
assert '__version__ = "0.5.25"' in version_py_content
|
|
|
|
# Verify plugins/openclaw/package.json
|
|
openclaw_pkg = json.loads(temp_project["openclaw_pkg"].read_text())
|
|
assert openclaw_pkg["version"] == "0.7.0"
|
|
assert openclaw_pkg["dependencies"]["headroom-ai"] == "^0.22.3"
|
|
|
|
# Verify sdk/typescript/package.json
|
|
typescript_pkg = json.loads(temp_project["typescript_pkg"].read_text())
|
|
assert typescript_pkg["version"] == "0.7.0"
|
|
|
|
repo_claude_marketplace = json.loads(temp_project["repo_claude_marketplace"].read_text())
|
|
assert repo_claude_marketplace["metadata"]["version"] == "0.7.0"
|
|
assert repo_claude_marketplace["plugins"][0]["version"] == "0.7.0"
|
|
|
|
repo_github_marketplace = json.loads(temp_project["repo_github_marketplace"].read_text())
|
|
assert repo_github_marketplace["metadata"]["version"] == "0.7.0"
|
|
assert repo_github_marketplace["plugins"][0]["version"] == "0.7.0"
|
|
|
|
claude_plugin = json.loads(temp_project["claude_plugin"].read_text())
|
|
assert claude_plugin["version"] == "0.7.0"
|
|
|
|
github_plugin = json.loads(temp_project["github_plugin"].read_text())
|
|
assert github_plugin["version"] == "0.7.0"
|
|
|
|
# Verify .releasemetadata was created
|
|
release_metadata = root / ".releasemetadata"
|
|
assert release_metadata.exists()
|
|
metadata = json.loads(release_metadata.read_text())
|
|
assert metadata["version"] == "0.7.0"
|
|
assert metadata["packages"]["pypi"] == "0.7.0"
|
|
assert metadata["packages"]["npm-sdk"] == "0.7.0"
|
|
assert metadata["packages"]["npm-openclaw"] == "0.7.0"
|
|
assert metadata["packages"]["agent-hooks-plugin"] == "0.7.0"
|
|
|
|
|
|
def test_bump_patch(temp_project: dict[str, Path]) -> None:
|
|
"""Test --bump patch bumps 0.5.25 to 0.5.26."""
|
|
root = temp_project["root"]
|
|
script = Path(__file__).parent.parent / "version-sync.py"
|
|
|
|
result = subprocess.run(
|
|
[sys.executable, str(script), "--root", str(root), "--bump", "patch"],
|
|
capture_output=True,
|
|
text=True,
|
|
)
|
|
|
|
assert result.returncode == 0, f"Script failed: {result.stderr}"
|
|
|
|
# Verify all files updated to 0.5.26
|
|
pyproject_content = temp_project["pyproject"].read_text()
|
|
assert 'version = "0.5.26"' in pyproject_content
|
|
|
|
version_py_content = temp_project["version_py"].read_text()
|
|
assert '__version__ = "0.5.25"' in version_py_content
|
|
|
|
openclaw_pkg = json.loads(temp_project["openclaw_pkg"].read_text())
|
|
assert openclaw_pkg["version"] == "0.5.26"
|
|
assert openclaw_pkg["dependencies"]["headroom-ai"] == "^0.22.3"
|
|
|
|
typescript_pkg = json.loads(temp_project["typescript_pkg"].read_text())
|
|
assert typescript_pkg["version"] == "0.5.26"
|
|
|
|
claude_plugin = json.loads(temp_project["claude_plugin"].read_text())
|
|
assert claude_plugin["version"] == "0.5.26"
|
|
|
|
|
|
def test_bump_minor(temp_project: dict[str, Path]) -> None:
|
|
"""Test --bump minor bumps 0.5.25 to 0.6.0."""
|
|
root = temp_project["root"]
|
|
script = Path(__file__).parent.parent / "version-sync.py"
|
|
|
|
result = subprocess.run(
|
|
[sys.executable, str(script), "--root", str(root), "--bump", "minor"],
|
|
capture_output=True,
|
|
text=True,
|
|
)
|
|
|
|
assert result.returncode == 0, f"Script failed: {result.stderr}"
|
|
|
|
# Verify all files updated to 0.6.0
|
|
pyproject_content = temp_project["pyproject"].read_text()
|
|
assert 'version = "0.6.0"' in pyproject_content
|
|
|
|
version_py_content = temp_project["version_py"].read_text()
|
|
assert '__version__ = "0.5.25"' in version_py_content
|
|
|
|
openclaw_pkg = json.loads(temp_project["openclaw_pkg"].read_text())
|
|
assert openclaw_pkg["version"] == "0.6.0"
|
|
assert openclaw_pkg["dependencies"]["headroom-ai"] == "^0.22.3"
|
|
|
|
typescript_pkg = json.loads(temp_project["typescript_pkg"].read_text())
|
|
assert typescript_pkg["version"] == "0.6.0"
|
|
|
|
github_plugin = json.loads(temp_project["github_plugin"].read_text())
|
|
assert github_plugin["version"] == "0.6.0"
|
|
|
|
|
|
def test_bump_major(temp_project: dict[str, Path]) -> None:
|
|
"""Test --bump major bumps 0.5.25 to 1.0.0."""
|
|
root = temp_project["root"]
|
|
script = Path(__file__).parent.parent / "version-sync.py"
|
|
|
|
result = subprocess.run(
|
|
[sys.executable, str(script), "--root", str(root), "--bump", "major"],
|
|
capture_output=True,
|
|
text=True,
|
|
)
|
|
|
|
assert result.returncode == 0, f"Script failed: {result.stderr}"
|
|
|
|
# Verify all files updated to 1.0.0
|
|
pyproject_content = temp_project["pyproject"].read_text()
|
|
assert 'version = "1.0.0"' in pyproject_content
|
|
|
|
version_py_content = temp_project["version_py"].read_text()
|
|
assert '__version__ = "0.5.25"' in version_py_content
|
|
|
|
openclaw_pkg = json.loads(temp_project["openclaw_pkg"].read_text())
|
|
assert openclaw_pkg["version"] == "1.0.0"
|
|
assert openclaw_pkg["dependencies"]["headroom-ai"] == "^0.22.3"
|
|
|
|
typescript_pkg = json.loads(temp_project["typescript_pkg"].read_text())
|
|
assert typescript_pkg["version"] == "1.0.0"
|
|
|
|
repo_claude_marketplace = json.loads(temp_project["repo_claude_marketplace"].read_text())
|
|
assert repo_claude_marketplace["metadata"]["version"] == "1.0.0"
|
|
|
|
|
|
def test_release_metadata_written(temp_project: dict[str, Path]) -> None:
|
|
"""Test .releasemetadata is written correctly."""
|
|
root = temp_project["root"]
|
|
script = Path(__file__).parent.parent / "version-sync.py"
|
|
|
|
result = subprocess.run(
|
|
[sys.executable, str(script), "--root", str(root), "--version", "0.6.0"],
|
|
capture_output=True,
|
|
text=True,
|
|
)
|
|
|
|
assert result.returncode == 0, f"Script failed: {result.stderr}"
|
|
|
|
release_metadata = root / ".releasemetadata"
|
|
assert release_metadata.exists()
|
|
|
|
metadata = json.loads(release_metadata.read_text())
|
|
assert metadata == {
|
|
"version": "0.6.0",
|
|
"packages": {
|
|
"pypi": "0.6.0",
|
|
"npm-sdk": "0.6.0",
|
|
"npm-openclaw": "0.6.0",
|
|
"agent-hooks-plugin": "0.6.0",
|
|
},
|
|
}
|
|
|
|
|
|
def test_plugin_manifests_only_leaves_package_versions_unchanged(
|
|
temp_project: dict[str, Path],
|
|
) -> None:
|
|
"""Test plugin-only sync leaves canonical package versions alone."""
|
|
root = temp_project["root"]
|
|
script = Path(__file__).parent.parent / "version-sync.py"
|
|
|
|
result = subprocess.run(
|
|
[
|
|
sys.executable,
|
|
str(script),
|
|
"--root",
|
|
str(root),
|
|
"--version",
|
|
"0.8.0",
|
|
"--plugin-manifests-only",
|
|
],
|
|
capture_output=True,
|
|
text=True,
|
|
)
|
|
|
|
assert result.returncode == 0, f"Script failed: {result.stderr}"
|
|
assert 'version = "0.5.25"' in temp_project["pyproject"].read_text()
|
|
assert '__version__ = "0.5.25"' in temp_project["version_py"].read_text()
|
|
assert json.loads(temp_project["openclaw_pkg"].read_text())["version"] == "0.5.25"
|
|
assert json.loads(temp_project["typescript_pkg"].read_text())["version"] == "0.5.25"
|
|
assert json.loads(temp_project["claude_plugin"].read_text())["version"] == "0.8.0"
|
|
assert (
|
|
json.loads(temp_project["repo_github_marketplace"].read_text())["metadata"]["version"]
|
|
== "0.8.0"
|
|
)
|
|
assert not (root / ".releasemetadata").exists()
|
|
|
|
|
|
def test_openclaw_headroom_dependency_is_preserved_for_registry_installability(
|
|
temp_project: dict[str, Path],
|
|
) -> None:
|
|
"""Source package stays installable even when the next SDK is not on npm yet."""
|
|
root = temp_project["root"]
|
|
script = Path(__file__).parent.parent / "version-sync.py"
|
|
|
|
result = subprocess.run(
|
|
[sys.executable, str(script), "--root", str(root), "--version", "0.28.0"],
|
|
capture_output=True,
|
|
text=True,
|
|
)
|
|
|
|
assert result.returncode == 0, f"Script failed: {result.stderr}"
|
|
openclaw_pkg = json.loads(temp_project["openclaw_pkg"].read_text())
|
|
assert openclaw_pkg["version"] == "0.28.0"
|
|
assert openclaw_pkg["dependencies"]["headroom-ai"] == "^0.22.3"
|
|
|
|
|
|
def test_server_json_version_is_synchronized(temp_project: dict[str, Path]) -> None:
|
|
"""server.json must track the bump or the release PR's test job fails.
|
|
|
|
``tests/test_mcp_registry/test_server_json.py::test_root_server_json_matches_builder``
|
|
asserts the tracked file equals ``render_server_json()``, which reads the version
|
|
from ``pyproject.toml``. Nothing regenerated server.json, so it fell behind every
|
|
release and blocked v0.33.0 (PR #2339).
|
|
"""
|
|
root = temp_project["root"]
|
|
script = Path(__file__).parent.parent / "version-sync.py"
|
|
|
|
result = subprocess.run(
|
|
[sys.executable, str(script), "--root", str(root), "--version", "0.33.0"],
|
|
capture_output=True,
|
|
text=True,
|
|
)
|
|
|
|
assert result.returncode == 0, f"Script failed: {result.stderr}"
|
|
server_json = json.loads(temp_project["server_json"].read_text())
|
|
assert server_json["version"] == "0.33.0"
|
|
# The packages[] entry carries its own version and is checked by the builder too.
|
|
assert [p["version"] for p in server_json["packages"]] == ["0.33.0"]
|
|
# Untouched keys must survive so the file still matches the builder's output.
|
|
assert server_json["name"] == "io.github.headroomlabs-ai/headroom"
|
|
assert server_json["packages"][0]["registryType"] == "pypi"
|