mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
## 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>
255 lines
8.9 KiB
Python
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()
|