Files
headroom/scripts/version-sync.py
66e1467682 feat(plugins): headroom skill for Claude Code, Codex, Copilot and skills.sh (#4533)
## Description

In the unbranded sandbox run the agent never searched and wrote a
300-line trimmer by hand; nothing in its environment said Headroom
exists. An Agent Skill is the one artifact that fires on the job words
(cut input tokens, trim tool outputs, fit a context window) with zero
fetches. Four unofficial "headroom" skills already exist on skills.sh;
there is no official one.

Depends on #4529 for the `/docs/fastapi` link in the skill body.

## Type of Change

- [x] New feature (non-breaking change that adds functionality)

## Changes Made

- `skills/headroom/SKILL.md`: job-language description; body is the
no-key `compress()` path, the zero-network check, `model_limit` /
`protect_recent`, the TypeScript proxy caveat, the coding-agent path,
and a short do-not list (no savings claims, no `CompressionMiddleware`
for apps that call a provider, no `[all]` unless asked).
- `plugins/headroom-skill/`: the same SKILL.md under `skills/`,
`.claude-plugin/plugin.json` and `.github/plugin/plugin.json`
(identical), README with install lines for Claude Code, Copilot CLI and
`npx skills add`.
- Both marketplace manifests: `headroom-skill` entry, inserted after the
hooks plugin so `plugins[0]` stays as the existing tests expect.
- `scripts/version-sync.py` and `scripts/verify-versions.py`: the two
new manifests, so the next release PR passes the version gate.
`scripts/tests/test_version_sync.py` fixture and assertion extended;
`tests/test_release_workflows.py` gate list extended.
- `tests/test_plugin_manifests.py`: the two SKILL.md copies must be
byte-identical (the repo has no symlinks, for Windows checkouts),
frontmatter has `name: headroom`; the skill plugin's two manifests match
each other and the marketplace entry.

## Testing

- [x] Unit tests pass: `tests/test_plugin_manifests.py
scripts/tests/test_version_sync.py tests/test_release_workflows.py -k
"manifest or version or skill or sync"`: 30 passed
- [x] `ruff check` / `ruff format --check` on the touched Python
- [x] `python scripts/verify-versions.py`: "All versions aligned at
0.42.0"
- [x] Manual testing performed

### Test Output

```text
pytest tests/test_plugin_manifests.py scripts/tests/test_version_sync.py tests/test_release_workflows.py -k "manifest or version or skill or sync": 30 passed
python scripts/verify-versions.py: All versions aligned at 0.42.0
claude plugin validate .: ✔ Validation passed
```

## Real Behavior Proof

- Environment: macOS arm64, Claude Code CLI.
- Exact command / steps: `claude plugin validate .` at the repo root of
this branch.
- Observed result: `✔ Validation passed`. The only warning is
pre-existing and about `plugins/headroom-agent-hooks/README.md` lacking
a marketplace install line.
- Not tested: installing the plugin from the marketplace into a fresh
Claude Code or Copilot CLI session and triggering the skill on a real
task; skills.sh indexing (happens on their side once this is on `main`).

## Runtime Rollout Safety

- Rollout-managed feature(s): none; documentation and metadata only, no
runtime code path changes
- Minimum rollout channel: n/a
- Stable/default behavior changed: no
- Kill switch / disable path: n/a (revert the PR)
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the commit

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-03 23:43:21 -06:00

255 lines
8.9 KiB
Python

#!/usr/bin/env python3
"""Synchronize version across all headroom packages."""
from __future__ import annotations
import argparse
import json
import re
from pathlib import Path
try:
import tomllib
except ImportError: # pragma: no cover - Python 3.10 fallback
import tomli as tomllib
def get_version_from_pyproject(root: Path) -> str:
"""Read version from pyproject.toml."""
pyproject_path = root / "pyproject.toml"
with open(pyproject_path, "rb") as f:
data = tomllib.load(f)
return data["project"]["version"]
def bump_version(version: str, bump_type: str) -> str:
"""Bump version according to bump_type (major, minor, patch)."""
major, minor, patch = map(int, version.split("."))
if bump_type == "major":
major += 1
minor = 0
patch = 0
elif bump_type == "minor":
minor += 1
patch = 0
elif bump_type == "patch":
patch += 1
return f"{major}.{minor}.{patch}"
def update_package_json(file_path: Path, version: str) -> None:
"""Update a package.json version field."""
with open(file_path, encoding="utf-8") as f:
data = json.load(f)
data["version"] = version
with open(file_path, "w", encoding="utf-8") as f:
json.dump(data, f, indent=2, ensure_ascii=False)
f.write("\n")
def update_plugin_manifest(file_path: Path, version: str) -> None:
"""Update a plugin.json version field."""
with open(file_path, encoding="utf-8") as f:
data = json.load(f)
data["version"] = version
with open(file_path, "w", encoding="utf-8") as f:
json.dump(data, f, indent=2, ensure_ascii=False)
f.write("\n")
def update_marketplace_manifest(file_path: Path, version: str) -> None:
"""Update marketplace metadata and plugin entry versions."""
with open(file_path, encoding="utf-8") as f:
data = json.load(f)
metadata = data.get("metadata")
if isinstance(metadata, dict):
metadata["version"] = version
plugins = data.get("plugins")
if isinstance(plugins, list):
for plugin in plugins:
if isinstance(plugin, dict):
plugin["version"] = version
with open(file_path, "w", encoding="utf-8") as f:
json.dump(data, f, indent=2, ensure_ascii=False)
f.write("\n")
def update_server_json(file_path: Path, version: str) -> None:
"""Update the MCP registry descriptor's version fields.
``server.json`` is asserted byte-for-byte against ``render_server_json()``
(tests/test_mcp_registry/test_server_json.py), which derives the version from
``pyproject.toml``. Nothing regenerated this file, so it silently fell behind
every release and failed that test on the release PR. Values are rewritten in
place so key order and formatting keep matching the builder's output.
"""
with open(file_path, encoding="utf-8") as f:
data = json.load(f)
data["version"] = version
packages = data.get("packages")
if isinstance(packages, list):
for package in packages:
if isinstance(package, dict):
package["version"] = version
with open(file_path, "w", encoding="utf-8") as f:
json.dump(data, f, indent=2, ensure_ascii=False)
f.write("\n")
def update_plugin_versions(root: Path, version: str) -> None:
"""Update marketplace and plugin manifest versions."""
update_marketplace_manifest(root / ".claude-plugin" / "marketplace.json", version)
update_marketplace_manifest(root / ".github" / "plugin" / "marketplace.json", version)
update_plugin_manifest(
root / "plugins" / "headroom-agent-hooks" / ".claude-plugin" / "plugin.json", version
)
update_plugin_manifest(
root / "plugins" / "headroom-agent-hooks" / ".github" / "plugin" / "plugin.json",
version,
)
update_plugin_manifest(
root / "plugins" / "headroom-snip" / ".claude-plugin" / "plugin.json", version
)
update_plugin_manifest(
root / "plugins" / "headroom-skill" / ".claude-plugin" / "plugin.json", version
)
update_plugin_manifest(
root / "plugins" / "headroom-skill" / ".github" / "plugin" / "plugin.json", version
)
def update_openclaw_package_json(file_path: Path, version: str) -> None:
"""Update openclaw package.json version.
Keep the source `headroom-ai` dependency registry-installable. The release
workflow rewrites the packed tgz dependency to the exact release range after
the local SDK tarball is available.
"""
with open(file_path, encoding="utf-8") as f:
data = json.load(f)
data["version"] = version
with open(file_path, "w", encoding="utf-8") as f:
json.dump(data, f, indent=2, ensure_ascii=False)
f.write("\n")
def update_opencode_package_json(file_path: Path, version: str) -> None:
"""Update opencode package.json version.
Keep the source `headroom-ai` dependency registry-installable. The release
workflow rewrites the packed dependency to the exact release range right
before npm publication.
"""
with open(file_path, encoding="utf-8") as f:
data = json.load(f)
data["version"] = version
with open(file_path, "w", encoding="utf-8") as f:
json.dump(data, f, indent=2, ensure_ascii=False)
f.write("\n")
def update_pyproject_version(root: Path, version: str) -> None:
"""Update pyproject.toml version."""
pyproject_path = root / "pyproject.toml"
content = pyproject_path.read_text(encoding="utf-8")
updated = re.sub(
r'^version = "[^"]+"',
f'version = "{version}"',
content,
flags=re.MULTILINE,
)
pyproject_path.write_text(updated, encoding="utf-8")
def write_release_metadata(root: Path, version: str) -> None:
"""Write .releasemetadata JSON file."""
metadata = {
"version": version,
"packages": {
"pypi": version,
"npm-sdk": version,
"npm-openclaw": version,
"npm-opencode": version,
"agent-hooks-plugin": version,
},
}
metadata_path = root / ".releasemetadata"
with open(metadata_path, "w", encoding="utf-8") as f:
json.dump(metadata, f, indent=2, ensure_ascii=False)
f.write("\n")
def update_uv_lock_version(root: Path, version: str) -> None:
"""Sync only the editable project's version without resolving dependencies."""
lock_path = root / "uv.lock"
if not lock_path.exists():
return
content = lock_path.read_text(encoding="utf-8")
packages = tomllib.loads(content).get("package", [])
editable = [p for p in packages if p.get("source", {}).get("editable") == "."]
if len(editable) != 1:
raise ValueError("uv.lock must contain exactly one editable root package")
package = editable[0]
if package["version"] == version:
return
pattern = (
rf'(?m)(^name = {re.escape(json.dumps(package["name"]))}\nversion = )"[^"\n]+"'
r'(?=\nsource = \{ editable = "\." \})'
)
updated, count = re.subn(pattern, lambda match: match[1] + json.dumps(version), content)
if count != 1:
raise ValueError("Cannot locate canonical editable root version in uv.lock")
lock_path.write_text(updated, encoding="utf-8", newline="\n")
def main() -> None:
parser = argparse.ArgumentParser(description="Synchronize version across headroom packages")
parser.add_argument(
"--root",
type=Path,
default=Path(__file__).parent.parent,
help="Root directory of the project",
)
group = parser.add_mutually_exclusive_group()
group.add_argument("--version", help="Explicit version to set (e.g., 0.6.0)")
group.add_argument(
"--bump",
choices=["major", "minor", "patch"],
help="Bump version from pyproject.toml",
)
parser.add_argument(
"--plugin-manifests-only",
action="store_true",
help="Only update marketplace/plugin manifest versions",
)
args = parser.parse_args()
if args.version:
version = args.version
elif args.bump:
base_version = get_version_from_pyproject(args.root)
version = bump_version(base_version, args.bump)
else:
version = get_version_from_pyproject(args.root)
if args.plugin_manifests_only:
update_plugin_versions(args.root, version)
print(f"Plugin versions synchronized to {version}")
return
# Update all versioned files
update_pyproject_version(args.root, version)
update_uv_lock_version(args.root, version)
update_openclaw_package_json(args.root / "plugins" / "openclaw" / "package.json", version)
update_opencode_package_json(args.root / "plugins" / "opencode" / "package.json", version)
update_package_json(args.root / "sdk" / "typescript" / "package.json", version)
update_plugin_versions(args.root, version)
update_server_json(args.root / "server.json", version)
write_release_metadata(args.root, version)
print(f"Version synchronized to {version}")
if __name__ == "__main__":
main()