The stewardship skills were written by exactly one code path: `init`, which
only runs on a new repository. Adopting an existing one starts from the
repository-adoption skill, and nothing could put that skill there -- so the
entry point to the procedure depended on the operator already having it
from somewhere else. Services/Monitoring carries three domain skills of its
own and no stewardship skill; `adopt` lists `.claude/skills` among its
collision paths and installs nothing.
repoctl skills install --repo . # travels with the repository
repoctl skills install --global # follows the operator everywhere
repoctl skills status --repo .
Scope is stated, never guessed: the two answers differ in who ends up with
the skills, and neither is the obvious default.
No plan and no approval hash. That discipline protects a repository's own
content; this writes only tool-owned files, in a fixed subdirectory, whose
content is fully determined by the installed version. The house rule it
does keep is that a write never destroys what it did not author: a skill
whose content differs is reported as SKILLS_MODIFIED and left alone until
`--force` says otherwise, and the check covers every skill before the first
byte is written, so a refusal leaves nothing half-updated.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
148 lines
5.5 KiB
Python
148 lines
5.5 KiB
Python
"""`repoctl skills`: the entry point that made adoption reachable at all.
|
|
|
|
Before this command the stewardship skills were written by exactly one code
|
|
path -- `init`, which only runs on a *new* repository. Adopting an existing one
|
|
needs the adoption skill, and nothing could put it there, so the procedure's
|
|
entry point depended on the operator already having the skill from elsewhere.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
from pathlib import Path
|
|
|
|
import pytest
|
|
|
|
from stewardship import skills
|
|
from stewardship.cli import main
|
|
|
|
|
|
def _states(base: Path) -> dict[str, str]:
|
|
return {item["skill"]: item["state"] for item in skills.status(base)}
|
|
|
|
|
|
# --- scope has to be stated ---------------------------------------------------
|
|
|
|
def test_scope_must_be_stated() -> None:
|
|
"""Guessing between "this repository" and "every repository" is not possible."""
|
|
with pytest.raises(skills.SkillsError) as excinfo:
|
|
skills.target_base(None, global_scope=False)
|
|
assert excinfo.value.code == "SKILLS_SCOPE_MISSING"
|
|
|
|
|
|
def test_two_scopes_at_once_are_refused(tmp_path: Path) -> None:
|
|
with pytest.raises(skills.SkillsError) as excinfo:
|
|
skills.target_base(tmp_path, global_scope=True)
|
|
assert excinfo.value.code == "SKILLS_SCOPE_AMBIGUOUS"
|
|
|
|
|
|
def test_a_missing_target_directory_is_refused(tmp_path: Path) -> None:
|
|
with pytest.raises(skills.SkillsError) as excinfo:
|
|
skills.target_base(tmp_path / "nope", global_scope=False)
|
|
assert excinfo.value.code == "SKILLS_TARGET_MISSING"
|
|
|
|
|
|
# --- install ------------------------------------------------------------------
|
|
|
|
def test_install_writes_every_skill_into_a_bare_directory(tmp_path: Path) -> None:
|
|
assert set(_states(tmp_path).values()) == {"missing"}
|
|
|
|
result = skills.install(tmp_path)
|
|
|
|
assert result["installed"] == sorted(skills.SKILLS)
|
|
assert set(_states(tmp_path).values()) == {"current"}
|
|
for name in skills.SKILLS:
|
|
assert (tmp_path / ".claude" / "skills" / name / "SKILL.md").is_file()
|
|
|
|
|
|
def test_install_is_idempotent(tmp_path: Path) -> None:
|
|
skills.install(tmp_path)
|
|
second = skills.install(tmp_path)
|
|
assert second["installed"] == []
|
|
assert second["unchanged"] == sorted(skills.SKILLS)
|
|
|
|
|
|
def test_install_writes_only_what_is_missing(tmp_path: Path) -> None:
|
|
skills.install(tmp_path)
|
|
(tmp_path / ".claude" / "skills" / "repo-handoff" / "SKILL.md").unlink()
|
|
|
|
result = skills.install(tmp_path)
|
|
|
|
assert result["installed"] == ["repo-handoff"]
|
|
|
|
|
|
# --- a write never destroys what it did not author ---------------------------
|
|
|
|
def test_a_modified_skill_is_reported_not_overwritten(tmp_path: Path) -> None:
|
|
skills.install(tmp_path)
|
|
edited = tmp_path / ".claude" / "skills" / "repository-adoption" / "SKILL.md"
|
|
edited.write_text("# locally rewritten\n", encoding="utf-8")
|
|
|
|
with pytest.raises(skills.SkillsError) as excinfo:
|
|
skills.install(tmp_path)
|
|
|
|
assert excinfo.value.code == "SKILLS_MODIFIED"
|
|
assert "--force" in str(excinfo.value)
|
|
assert edited.read_text(encoding="utf-8") == "# locally rewritten\n"
|
|
|
|
|
|
def test_a_refusal_writes_nothing_at_all(tmp_path: Path) -> None:
|
|
"""The check runs over every skill before the first byte is written."""
|
|
skills.install(tmp_path)
|
|
(tmp_path / ".claude" / "skills" / "repo-handoff" / "SKILL.md").write_text("edited\n", encoding="utf-8")
|
|
(tmp_path / ".claude" / "skills" / "repository-adoption" / "SKILL.md").unlink()
|
|
|
|
with pytest.raises(skills.SkillsError):
|
|
skills.install(tmp_path)
|
|
|
|
assert _states(tmp_path)["repository-adoption"] == "missing"
|
|
|
|
|
|
def test_force_replaces_only_the_divergent_skill(tmp_path: Path) -> None:
|
|
skills.install(tmp_path)
|
|
(tmp_path / ".claude" / "skills" / "repo-handoff" / "SKILL.md").write_text("edited\n", encoding="utf-8")
|
|
|
|
result = skills.install(tmp_path, force=True)
|
|
|
|
assert result["installed"] == ["repo-handoff"]
|
|
assert set(_states(tmp_path).values()) == {"current"}
|
|
|
|
|
|
# --- what lands is what this version ships -----------------------------------
|
|
|
|
def test_installed_skills_match_the_shipped_constants(tmp_path: Path) -> None:
|
|
skills.install(tmp_path)
|
|
for name, content in skills.SKILLS.items():
|
|
on_disk = (tmp_path / ".claude" / "skills" / name / "SKILL.md").read_text(encoding="utf-8")
|
|
assert on_disk.strip() == content.strip()
|
|
|
|
|
|
def test_the_adoption_skill_is_among_them() -> None:
|
|
"""The one whose absence made adopting an existing repository unreachable."""
|
|
assert "repository-adoption" in skills.SKILLS
|
|
|
|
|
|
# --- CLI ----------------------------------------------------------------------
|
|
|
|
def test_cli_install_then_status(tmp_path: Path, capsys) -> None:
|
|
assert main(["skills", "install", "--repo", str(tmp_path), "--output", "json"]) == 0
|
|
envelope = json.loads(capsys.readouterr().out)
|
|
assert envelope["outcome"] == "success"
|
|
assert envelope["data"]["installed"] == sorted(skills.SKILLS)
|
|
|
|
assert main(["skills", "status", "--repo", str(tmp_path), "--output", "json"]) == 0
|
|
envelope = json.loads(capsys.readouterr().out)
|
|
assert {item["state"] for item in envelope["data"]["skills"]} == {"current"}
|
|
|
|
|
|
def test_cli_refusal_is_an_envelope(tmp_path: Path, capsys) -> None:
|
|
skills.install(tmp_path)
|
|
(tmp_path / ".claude" / "skills" / "repo-handoff" / "SKILL.md").write_text("edited\n", encoding="utf-8")
|
|
|
|
exit_code = main(["skills", "install", "--repo", str(tmp_path), "--output", "json"])
|
|
|
|
envelope = json.loads(capsys.readouterr().out)
|
|
assert exit_code != 0
|
|
assert envelope["outcome"] == "failure"
|
|
assert envelope["findings"][0]["code"] == "SKILLS_MODIFIED"
|