recx-cli 0.0.1__tar.gz → 0.0.2__tar.gz

{recx_cli-0.0.1 → recx_cli-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: recx-cli
-Version: 0.0.1
+Version: 0.0.2
 Summary: Validator for RECX.yaml manifests: the recx check command.
 Project-URL: Homepage, https://github.com/jbmv/recx
 Project-URL: Repository, https://github.com/jbmv/recx
@@ -35,6 +35,23 @@ One line per problem, `<file>: <json-pointer>: <message>`, or `<file>: valid`. E
 means valid, 1 invalid, 2 a usage error or an unreadable file. `recx check` does not yet
 check that the license file agrees with `license` (rule 4 of the spec).
 
+## The Claude Code plugin
+
+The `recx` plugin adds the `/recx:manifest` skill, for writing and maintaining a `RECX.yaml`,
+and a Stop hook that keeps the manifest valid as a session ends.
+
+```
+/plugin marketplace add jbmv/recx
+/plugin install recx@recx
+```
+
+On Claude Code 2.1.275 or later, `/plugin install recx --marketplace jbmv/recx` does both in one
+step. The hook runs `recx hook stop`, from `recx` on your PATH or else through `uvx`; it needs
+recx-cli 0.0.2 or later, and a missing `recx` never blocks a session. `RECX_STOP_HOOK` sets it:
+`block` (the default), `warn` for feedback only, or `off`.
+
+To adopt recx in a repository with any coding agent, see [ADOPT.md](ADOPT.md).
+
 The npm package `@jbmv/recx` ships the schema: `require('@jbmv/recx')` returns it.
 
 This README is an interim one. The full README is still to come.

{recx_cli-0.0.1 → recx_cli-0.0.2}/README.md

@@ -21,6 +21,23 @@ One line per problem, `<file>: <json-pointer>: <message>`, or `<file>: valid`. E
 means valid, 1 invalid, 2 a usage error or an unreadable file. `recx check` does not yet
 check that the license file agrees with `license` (rule 4 of the spec).
 
+## The Claude Code plugin
+
+The `recx` plugin adds the `/recx:manifest` skill, for writing and maintaining a `RECX.yaml`,
+and a Stop hook that keeps the manifest valid as a session ends.
+
+```
+/plugin marketplace add jbmv/recx
+/plugin install recx@recx
+```
+
+On Claude Code 2.1.275 or later, `/plugin install recx --marketplace jbmv/recx` does both in one
+step. The hook runs `recx hook stop`, from `recx` on your PATH or else through `uvx`; it needs
+recx-cli 0.0.2 or later, and a missing `recx` never blocks a session. `RECX_STOP_HOOK` sets it:
+`block` (the default), `warn` for feedback only, or `off`.
+
+To adopt recx in a repository with any coding agent, see [ADOPT.md](ADOPT.md).
+
 The npm package `@jbmv/recx` ships the schema: `require('@jbmv/recx')` returns it.
 
 This README is an interim one. The full README is still to come.

{recx_cli-0.0.1 → recx_cli-0.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "recx-cli"
-version = "0.0.1"
+version = "0.0.2"
 description = "Validator for RECX.yaml manifests: the recx check command."
 readme = "README.md"
 requires-python = ">=3.10"

{recx_cli-0.0.1 → recx_cli-0.0.2}/src/recx_cli/check.py

@@ -29,6 +29,11 @@ class Problem:
     message: str
 
 
+def format_problem(label: str, problem: Problem) -> str:
+    """One problem as `recx check` prints it."""
+    return f"{label}: {problem.pointer}: {problem.message}"
+
+
 # -- schema ---------------------------------------------------------------
 
 

{recx_cli-0.0.1 → recx_cli-0.0.2}/src/recx_cli/cli.py

@@ -7,7 +7,7 @@ import sys
 from importlib import metadata
 from pathlib import Path
 
-from recx_cli.check import Unreadable, check_file
+from recx_cli.check import Unreadable, check_file, format_problem
 
 
 def _version() -> str:
@@ -45,11 +45,28 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="skip the checks that look at the repository (rule 3: module paths exist)",
     )
+    hook = sub.add_parser(
+        "hook",
+        help="entry points for Claude Code hooks",
+        description="Commands that Claude Code hooks run. They read the hook's JSON on stdin.",
+    )
+    hook_sub = hook.add_subparsers(dest="hook_command", required=True, parser_class=_Parser)
+    hook_sub.add_parser(
+        "stop",
+        help="Stop hook: keep the repository's RECX.yaml valid as a session ends",
+        description="Read Claude Code's Stop hook JSON on stdin. Always exits 0. "
+        "RECX_STOP_HOOK=block (default) blocks the stop while RECX.yaml is invalid, "
+        "warn only gives feedback, off does nothing.",
+    )
     return parser
 
 
 def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
+    if args.command == "hook":
+        from recx_cli.hook import stop
+
+        return stop()
     target = Path(args.path)
     if target.is_dir():
         target = target / "RECX.yaml"
@@ -63,5 +80,5 @@ def main(argv: list[str] | None = None) -> int:
         print(f"{label}: valid")
         return 0
     for p in problems:
-        print(f"{label}: {p.pointer}: {p.message}")
+        print(format_problem(label, p))
     return 1

recx_cli-0.0.2/src/recx_cli/hook.py

@@ -0,0 +1,89 @@
+"""`recx hook stop`: Claude Code's Stop hook, keeping a RECX.yaml valid as a session ends.
+
+The hook must never trap a session on its own failure, so every error path
+exits 0 without output. Only an invalid manifest produces output, and it is
+always JSON on stdout with exit status 0.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from recx_cli.check import Unreadable, check_file, format_problem
+
+MANIFEST = "RECX.yaml"
+SKILL = "recx:manifest"
+
+
+def _mode() -> str:
+    value = os.environ.get("RECX_STOP_HOOK", "block").strip().lower()
+    return value if value in ("block", "warn", "off") else "block"
+
+
+def _manifest_dir(cwd: str) -> Path:
+    start = Path(cwd)
+    try:
+        out = subprocess.run(
+            ["git", "-C", str(start), "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        top = out.stdout.strip()
+        if out.returncode == 0 and top:
+            return Path(top)
+    except (OSError, subprocess.SubprocessError):
+        pass
+    return start
+
+
+def _run() -> None:
+    if _mode() == "off":
+        return
+    raw = sys.stdin.read()
+    if not raw.strip():
+        return
+    event = json.loads(raw)
+    if not isinstance(event, dict):
+        return
+    cwd = event.get("cwd")
+    if not isinstance(cwd, str) or not cwd:
+        return
+    manifest = _manifest_dir(cwd) / MANIFEST
+    if not manifest.is_file():
+        return
+    try:
+        problems = check_file(manifest, repo=True)
+    except Unreadable:
+        return
+    if not problems:
+        return
+    lines = "\n".join(format_problem(MANIFEST, p) for p in problems)
+    if _mode() == "block" and event.get("stop_hook_active") is not True:
+        reason = (
+            f"{MANIFEST} is invalid. Fix every problem below, using the {SKILL} skill, "
+            f"then check it with `recx check` (or `uvx --from recx-cli recx check`):\n{lines}"
+        )
+        print(json.dumps({"decision": "block", "reason": reason}))
+    else:
+        still = " still" if event.get("stop_hook_active") is True else ""
+        context = (
+            f"{MANIFEST} is{still} invalid. The {SKILL} skill explains how to fix it:\n{lines}"
+        )
+        print(
+            json.dumps(
+                {"hookSpecificOutput": {"hookEventName": "Stop", "additionalContext": context}}
+            )
+        )
+
+
+def stop() -> int:
+    try:
+        _run()
+    except BaseException:  # noqa: BLE001 - a hook failure must not block the session
+        pass
+    return 0

{recx_cli-0.0.1 → recx_cli-0.0.2}/tests/test_check.py

@@ -238,8 +238,8 @@ def test_build_produces_sdist_and_wheel(tmp_path):
     out = tmp_path / "dist"
     env = {k: v for k, v in __import__("os").environ.items() if k != "VIRTUAL_ENV"}
     subprocess.run(["uv", "build", "--out-dir", str(out)], cwd=ROOT, check=True, capture_output=True, env=env)
-    wheels = list(out.glob("recx_cli-0.0.1-*.whl"))
-    sdists = list(out.glob("recx_cli-0.0.1.tar.gz"))
+    wheels = list(out.glob("recx_cli-0.0.2-*.whl"))
+    sdists = list(out.glob("recx_cli-0.0.2.tar.gz"))
     assert len(wheels) == 1 and len(sdists) == 1
     with zipfile.ZipFile(wheels[0]) as z:
         names = z.namelist()

recx_cli-0.0.2/tests/test_hook.py

@@ -0,0 +1,219 @@
+import io
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from recx_cli import hook
+from recx_cli.cli import main
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPT = ROOT / "plugin" / "scripts" / "stop-hook.sh"
+
+VALID = """recx: "0.1"
+name: example
+summary: An example project.
+license: MIT
+status: experimental
+capabilities:
+  - do one thing
+"""
+INVALID = VALID.replace("status: experimental\n", "status: bogus\n")
+
+
+@pytest.fixture(autouse=True)
+def _no_env(monkeypatch):
+    monkeypatch.delenv("RECX_STOP_HOOK", raising=False)
+
+
+def stop(capsys, monkeypatch, stdin):
+    if not isinstance(stdin, str):
+        stdin = json.dumps(stdin)
+    monkeypatch.setattr(sys, "stdin", io.StringIO(stdin))
+    code = main(["hook", "stop"])
+    out = capsys.readouterr()
+    return code, out.out
+
+
+def event(cwd, **kw):
+    return {"hook_event_name": "Stop", "cwd": str(cwd), "stop_hook_active": False, **kw}
+
+
+def git_init(path):
+    subprocess.run(["git", "init", "-q", str(path)], check=True)
+
+
+def test_no_manifest_is_silent(capsys, monkeypatch, tmp_path):
+    assert stop(capsys, monkeypatch, event(tmp_path)) == (0, "")
+
+
+def test_valid_manifest_is_silent(capsys, monkeypatch, tmp_path):
+    (tmp_path / "RECX.yaml").write_text(VALID)
+    assert stop(capsys, monkeypatch, event(tmp_path)) == (0, "")
+
+
+def test_invalid_blocks_and_matches_recx_check(capsys, monkeypatch, tmp_path):
+    (tmp_path / "RECX.yaml").write_text(INVALID)
+    code, out = stop(capsys, monkeypatch, event(tmp_path))
+    assert code == 0
+    data = json.loads(out)
+    assert data["decision"] == "block" and "recx:manifest" in data["reason"]
+    assert main(["check", str(tmp_path / "RECX.yaml")]) == 1
+    check_lines = capsys.readouterr().out.splitlines()
+    assert check_lines
+    for line in check_lines:
+        assert line.split(": ", 1)[1] in data["reason"]
+
+
+def test_manifest_at_git_toplevel_from_subdirectory(capsys, monkeypatch, tmp_path):
+    git_init(tmp_path)
+    (tmp_path / "RECX.yaml").write_text(INVALID)
+    sub = tmp_path / "a" / "b"
+    sub.mkdir(parents=True)
+    code, out = stop(capsys, monkeypatch, event(sub))
+    assert code == 0 and json.loads(out)["decision"] == "block"
+
+
+def test_no_manifest_in_subdirectory_outside_git(capsys, monkeypatch, tmp_path):
+    sub = tmp_path / "sub"
+    sub.mkdir()
+    (tmp_path / "RECX.yaml").write_text(INVALID)
+    assert stop(capsys, monkeypatch, event(sub)) == (0, "")
+
+
+@pytest.mark.parametrize("how", ["active", "warn"])
+def test_feedback_without_block(capsys, monkeypatch, tmp_path, how):
+    (tmp_path / "RECX.yaml").write_text(INVALID)
+    if how == "warn":
+        monkeypatch.setenv("RECX_STOP_HOOK", "warn")
+        ev = event(tmp_path)
+    else:
+        ev = event(tmp_path, stop_hook_active=True)
+    code, out = stop(capsys, monkeypatch, ev)
+    data = json.loads(out)
+    assert code == 0 and "decision" not in data
+    spec = data["hookSpecificOutput"]
+    assert spec["hookEventName"] == "Stop" and "status" in spec["additionalContext"]
+
+
+def test_off_does_not_read_anything(capsys, monkeypatch, tmp_path):
+    (tmp_path / "RECX.yaml").write_text(INVALID)
+    monkeypatch.setenv("RECX_STOP_HOOK", "off")
+
+    class Boom:
+        def read(self):
+            raise AssertionError("stdin read")
+
+    monkeypatch.setattr(sys, "stdin", Boom())
+    monkeypatch.setattr(hook, "check_file", lambda *a, **k: pytest.fail("manifest read"))
+    assert main(["hook", "stop"]) == 0
+    assert capsys.readouterr().out == ""
+
+
+def test_unrecognised_value_behaves_as_block(capsys, monkeypatch, tmp_path):
+    (tmp_path / "RECX.yaml").write_text(INVALID)
+    monkeypatch.setenv("RECX_STOP_HOOK", "sometimes")
+    _, out = stop(capsys, monkeypatch, event(tmp_path))
+    assert json.loads(out)["decision"] == "block"
+
+
+@pytest.mark.parametrize(
+    "stdin", ["", "   \n", "{not json", "[1, 2]", "null", '{"hook_event_name": "Stop"}', '{"cwd": 5}']
+)
+def test_bad_input_never_blocks(capsys, monkeypatch, stdin):
+    assert stop(capsys, monkeypatch, stdin) == (0, "")
+
+
+def test_internal_error_never_blocks(capsys, monkeypatch, tmp_path):
+    (tmp_path / "RECX.yaml").write_text(INVALID)
+
+    def boom(*a, **k):
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(hook, "check_file", boom)
+    assert stop(capsys, monkeypatch, event(tmp_path)) == (0, "")
+
+
+def test_unreadable_manifest_never_blocks(capsys, monkeypatch, tmp_path):
+    (tmp_path / "RECX.yaml").mkdir()
+    assert stop(capsys, monkeypatch, event(tmp_path)) == (0, "")
+
+
+# -- the entry script ------------------------------------------------------
+
+
+def run_script(stdin, env_extra=None, path=None):
+    env = {k: v for k, v in os.environ.items() if k not in ("VIRTUAL_ENV", "RECX_STOP_HOOK")}
+    if path is not None:
+        env["PATH"] = path
+    env.update(env_extra or {})
+    return subprocess.run(["/bin/sh", str(SCRIPT)], input=stdin, capture_output=True, text=True, env=env)
+
+
+def test_script_is_executable_in_git():
+    out = subprocess.run(
+        ["git", "ls-files", "-s", "plugin/scripts/stop-hook.sh"], cwd=ROOT, capture_output=True, text=True
+    ).stdout
+    assert out.startswith("100755")
+
+
+def test_hooks_json_runs_the_script():
+    data = json.loads((ROOT / "plugin" / "hooks" / "hooks.json").read_text())
+    cmd = data["hooks"]["Stop"][0]["hooks"][0]["command"]
+    assert cmd == '"${CLAUDE_PLUGIN_ROOT}"/scripts/stop-hook.sh'
+    assert "matcher" not in data["hooks"]["Stop"][0]
+
+
+def test_script_end_to_end_blocks_in_git_repo(tmp_path):
+    git_init(tmp_path)
+    (tmp_path / "RECX.yaml").write_text(INVALID)
+    sub = tmp_path / "src"
+    sub.mkdir()
+    recx_dir = Path(sys.executable).parent
+    assert (recx_dir / "recx").exists()
+    path = f"{recx_dir}{os.pathsep}{os.environ['PATH']}"
+    r = run_script(json.dumps(event(sub)), path=path)
+    assert r.returncode == 0, r.stderr
+    data = json.loads(r.stdout)
+    assert data["decision"] == "block" and "recx:manifest" in data["reason"]
+
+
+def test_script_off_exits_at_once(tmp_path):
+    (tmp_path / "RECX.yaml").write_text(INVALID)
+    r = run_script(json.dumps(event(tmp_path)), {"RECX_STOP_HOOK": "off"})
+    assert (r.returncode, r.stdout) == (0, "")
+
+
+def test_script_without_recx_or_uvx_is_silent(tmp_path):
+    (tmp_path / "RECX.yaml").write_text(INVALID)
+    bindir = tmp_path / "bin"
+    bindir.mkdir()
+    r = run_script(json.dumps(event(tmp_path)), path=str(bindir))
+    assert (r.returncode, r.stdout) == (0, "")
+
+
+def test_script_with_outdated_recx_falls_through(tmp_path):
+    (tmp_path / "RECX.yaml").write_text(INVALID)
+    bindir = tmp_path / "bin"
+    bindir.mkdir()
+    old = bindir / "recx"
+    old.write_text("#!/bin/sh\nexit 2\n")
+    old.chmod(0o755)
+    r = run_script(json.dumps(event(tmp_path)), path=str(bindir))
+    assert (r.returncode, r.stdout) == (0, "")
+
+
+def test_script_never_passes_a_failing_status_through(tmp_path):
+    # Claude Code reads exit status 2 from a Stop hook as a block; uv exits 2 on
+    # some failures, so a failing uvx must not become a blocked session.
+    (tmp_path / "RECX.yaml").write_text(INVALID)
+    bindir = tmp_path / "bin"
+    bindir.mkdir()
+    uvx = bindir / "uvx"
+    uvx.write_text("#!/bin/sh\necho 'error: offline' >&2\nexit 2\n")
+    uvx.chmod(0o755)
+    r = run_script(json.dumps(event(tmp_path)), path=str(bindir))
+    assert (r.returncode, r.stdout) == (0, "")