Files
headroom/tests/test_plugin_manifests.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

146 lines
6.3 KiB
Python

from __future__ import annotations
import json
from pathlib import Path
import pytest
REPO_ROOT = Path(__file__).resolve().parents[1]
def _load_json(relative_path: str) -> object:
return json.loads((REPO_ROOT / relative_path).read_text(encoding="utf-8"))
# Plugins built on Claude Code's function hooks, which Copilot CLI cannot load.
CLAUDE_CODE_ONLY = {"headroom-snip"}
def test_marketplace_manifests_match() -> None:
claude = _load_json(".claude-plugin/marketplace.json")
assert isinstance(claude, dict)
shared = {
**claude,
"plugins": [p for p in claude["plugins"] if p["name"] not in CLAUDE_CODE_ONLY],
}
assert shared == _load_json(".github/plugin/marketplace.json")
def test_claude_code_only_plugins_are_listed_and_versioned() -> None:
marketplace = _load_json(".claude-plugin/marketplace.json")
assert isinstance(marketplace, dict)
for entry in marketplace["plugins"]:
if entry["name"] not in CLAUDE_CODE_ONLY:
continue
plugin_root = (REPO_ROOT / entry["source"]).resolve()
manifest = _load_json(f"{entry['source']}/.claude-plugin/plugin.json")
assert isinstance(manifest, dict)
assert manifest["name"] == entry["name"]
assert manifest["version"] == entry["version"] == marketplace["metadata"]["version"]
assert (plugin_root / "hooks" / "hooks.json").is_file()
@pytest.mark.parametrize("plugin", ["headroom-agent-hooks", "headroom-skill"])
def test_plugin_manifests_share_core_metadata(plugin: str) -> None:
claude = _load_json(f"plugins/{plugin}/.claude-plugin/plugin.json")
copilot = _load_json(f"plugins/{plugin}/.github/plugin/plugin.json")
assert isinstance(claude, dict)
assert isinstance(copilot, dict)
for key in ("name", "version", "description", "author", "homepage", "repository", "keywords"):
assert claude[key] == copilot[key]
assert "hooks" not in claude
if plugin == "headroom-agent-hooks":
assert copilot["hooks"] == "./hooks"
else:
assert "hooks" not in copilot
def test_plugin_hooks_timeout_exceeds_cold_start_wait() -> None:
"""The plugin's `ensure` hooks are killed by the host (Claude Code, etc.)
at their declared `timeout`, independent of anything inside the process.
Headroom's own cold-start path can take up to wait_ready's 45s ceiling
(headroom/cli/init.py), so a shorter external timeout makes the hook
unwinnable by construction on every session start (#3417)."""
hooks = _load_json("plugins/headroom-agent-hooks/hooks/hooks.json")
assert isinstance(hooks, dict)
for event in ("SessionStart", "PreToolUse"):
for entry in hooks["hooks"][event]:
for hook in entry["hooks"]:
assert hook["timeout"] > 45
def test_marketplace_entry_points_to_plugin_root() -> None:
marketplace = _load_json(".claude-plugin/marketplace.json")
assert isinstance(marketplace, dict)
plugins = marketplace["plugins"]
assert isinstance(plugins, list)
plugin = plugins[0]
assert plugin["name"] == "headroom"
plugin_root = (REPO_ROOT / plugin["source"]).resolve()
assert plugin_root.is_dir()
assert (plugin_root / ".claude-plugin" / "plugin.json").is_file()
assert (plugin_root / "hooks" / "hooks.json").is_file()
def test_plugin_metadata_points_to_upstream_repo() -> None:
expected_repo = "https://github.com/headroomlabs-ai/headroom"
marketplace = _load_json(".claude-plugin/marketplace.json")
claude = _load_json("plugins/headroom-agent-hooks/.claude-plugin/plugin.json")
assert isinstance(marketplace, dict)
assert isinstance(claude, dict)
plugin = marketplace["plugins"][0]
assert plugin["author"]["url"] == expected_repo
assert plugin["homepage"] == expected_repo
assert plugin["repository"] == expected_repo
assert claude["author"]["url"] == expected_repo
assert claude["homepage"] == expected_repo
assert claude["repository"] == expected_repo
def test_plugin_hooks_share_anchored_launcher_and_rootless_tail() -> None:
hooks = _load_json("plugins/headroom-agent-hooks/hooks/hooks.json")
assert isinstance(hooks, dict)
commands = [
entry["hooks"][0]["command"] for entries in hooks["hooks"].values() for entry in entries
]
expected = (
'sh -c \'[ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && launcher="${CLAUDE_PLUGIN_ROOT}/bin/headroom-hook.sh" && '
'[ -r "$launcher" ] && exec sh "$launcher"; '
"exec headroom init hook ensure'"
)
assert commands == [expected, expected]
powershell = [
entry["hooks"][0]["powershell"] for entries in hooks["hooks"].values() for entry in entries
]
assert powershell == ["headroom init hook ensure", "headroom init hook ensure"]
assert hooks["hooks"]["SessionStart"][0]["matcher"] == "startup|resume"
assert hooks["hooks"]["PreToolUse"][0]["matcher"] == "Bash|PowerShell"
launcher = REPO_ROOT / "plugins/headroom-agent-hooks/bin/headroom-hook.sh"
assert launcher.is_file()
assert b"\r" not in launcher.read_bytes()
def test_skill_plugin_ships_the_repo_root_skill() -> None:
"""The skill is published twice: at `skills/headroom` for skills.sh / Codex /
Cursor, which read the repo root, and inside the plugin for the Claude Code
and Copilot marketplaces, which read the plugin root. No symlinks (Windows
checkouts), so this test is what keeps the two copies identical."""
root_skill = REPO_ROOT / "skills" / "headroom" / "SKILL.md"
plugin_skill = REPO_ROOT / "plugins" / "headroom-skill" / "skills" / "headroom" / "SKILL.md"
assert root_skill.read_bytes() == plugin_skill.read_bytes()
head = root_skill.read_text(encoding="utf-8").split("---")[1]
assert "name: headroom\n" in head
assert "description: " in head
def test_skill_plugin_manifests_match_marketplace() -> None:
marketplace = _load_json(".claude-plugin/marketplace.json")
assert isinstance(marketplace, dict)
entry = next(p for p in marketplace["plugins"] if p["name"] == "headroom-skill")
claude = _load_json("plugins/headroom-skill/.claude-plugin/plugin.json")
assert isinstance(claude, dict)
for key in ("name", "version", "description", "author", "homepage", "repository", "keywords"):
assert claude[key] == entry[key]
assert entry["version"] == marketplace["metadata"]["version"]
assert (REPO_ROOT / entry["source"] / "skills" / "headroom" / "SKILL.md").is_file()