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

recx_cli-0.0.3/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: recx-cli
+Version: 0.0.3
+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
+Author: James Bullard
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: jsonschema[format-nongpl]>=4.18
+Requires-Dist: pyyaml>=6
+Description-Content-Type: text/markdown
+
+# recx
+
+*res extra commercium*: things outside commerce. A way for agents to find reusable, permissively
+licensed code from solo and small-team projects.
+
+A `RECX.yaml` at the root of a repository tells other people's coding agents what the repository
+does, which parts of it they can take on their own, and which checks show those parts work. recx
+is that format, a validator for it, and a Claude Code plugin that keeps the file current.
+
+## Why
+
+Coding agents have increased the amount of software that individuals and small teams produce.
+Much of it remains internal tooling, and the projects that are published are hard to find among
+the number of new repositories. Evaluating an unfamiliar open-source project also takes time, so
+writing a similar tool is often the quicker option, and comparable tools get written more than
+once.
+
+recx moves that search and evaluation to the agent doing the work, in two parts. The first is
+the manifest: a `RECX.yaml` in each participating repository that describes the project's
+capabilities, its separable modules and their interfaces, and the commands that verify them, in
+a fixed machine-readable form. The second is search: a way for an agent, while planning new
+work, to find manifests with relevant modules, check their evidence, and reuse a module rather
+than write it again, recording where it came from in its own project's manifest.
+
+Taking part is meant to cost a repository little. One prompt produces a complete, valid
+manifest, and the Claude Code plugin checks it whenever a session ends, so it stays valid as
+the code changes. No hosted service is involved, because the fixed filename serves as the index.
+On GitHub, manifests can be found by searching code for `path:/(^|\/)recx\.ya?ml$/i`.
+
+## The manifest
+
+```yaml
+recx: "0.1"
+name: tinyfmt
+summary: Formats byte counts as human-readable strings like 1.2 MB.
+license: MIT
+status: stable
+capabilities:
+  - format a byte count as a human-readable size string
+```
+
+Those six keys are the minimum. The optional parts carry most of the information: modules with
+interfaces and extraction notes, evidence anyone can rerun, and records of what was reused from
+where. [spec/SPEC.md](spec/SPEC.md) defines every field, puts a length limit on every string,
+and sets out how to read a stranger's manifest safely.
+
+Only permissively licensed projects qualify (MIT, Apache-2.0, the BSDs and similar), so
+anything listed can be reused without asking.
+
+## Get started
+
+- **Claude Code:** `/plugin marketplace add jbmv/recx`, then `/plugin install recx@recx`
+  (or, on Claude Code 2.1.275 or later, `/plugin install recx --marketplace jbmv/recx`). Then
+  ask Claude to add a RECX.yaml. A Stop hook keeps the manifest valid; set
+  `RECX_STOP_HOOK=warn` or `off` to soften or disable it.
+- **Any other agent:** paste the prompt in [ADOPT.md](ADOPT.md).
+- **By hand:** start from the example above, then run `uvx --from recx-cli recx check`.
+
+## What's here
+
+| | |
+|---|---|
+| [spec/](spec/) | The spec, its JSON Schema, and valid and invalid example manifests |
+| `recx-cli` on PyPI | `recx check`, the validator (`pip install recx-cli`) |
+| `@jbmv/recx` on npm | The schema and examples, for JavaScript tooling |
+| [plugin/](plugin/) | The Claude Code plugin; this repository is its marketplace |
+| [RECX.yaml](RECX.yaml) | recx's own manifest |
+
+## Status
+
+Experimental. The spec is a v0.1 draft and may change before 1.0; every manifest states the
+version it was written against. `recx check` enforces the whole spec except rule 4, that the
+license file matches `license`. The manifest, the validator and the plugin exist; search, the
+second part described above, is not built yet.
+
+## Kyosei
+
+I built recx for Kyosei, a record-keeping tool for running projects with coding agents. Kyosei
+isn't public yet. It will generate its own RECX.yaml from its records. Nothing in the spec
+depends on Kyosei: it is one client of the spec, like any other tool.
+
+## License
+
+MIT

recx_cli-0.0.3/README.md

@@ -0,0 +1,84 @@
+# recx
+
+*res extra commercium*: things outside commerce. A way for agents to find reusable, permissively
+licensed code from solo and small-team projects.
+
+A `RECX.yaml` at the root of a repository tells other people's coding agents what the repository
+does, which parts of it they can take on their own, and which checks show those parts work. recx
+is that format, a validator for it, and a Claude Code plugin that keeps the file current.
+
+## Why
+
+Coding agents have increased the amount of software that individuals and small teams produce.
+Much of it remains internal tooling, and the projects that are published are hard to find among
+the number of new repositories. Evaluating an unfamiliar open-source project also takes time, so
+writing a similar tool is often the quicker option, and comparable tools get written more than
+once.
+
+recx moves that search and evaluation to the agent doing the work, in two parts. The first is
+the manifest: a `RECX.yaml` in each participating repository that describes the project's
+capabilities, its separable modules and their interfaces, and the commands that verify them, in
+a fixed machine-readable form. The second is search: a way for an agent, while planning new
+work, to find manifests with relevant modules, check their evidence, and reuse a module rather
+than write it again, recording where it came from in its own project's manifest.
+
+Taking part is meant to cost a repository little. One prompt produces a complete, valid
+manifest, and the Claude Code plugin checks it whenever a session ends, so it stays valid as
+the code changes. No hosted service is involved, because the fixed filename serves as the index.
+On GitHub, manifests can be found by searching code for `path:/(^|\/)recx\.ya?ml$/i`.
+
+## The manifest
+
+```yaml
+recx: "0.1"
+name: tinyfmt
+summary: Formats byte counts as human-readable strings like 1.2 MB.
+license: MIT
+status: stable
+capabilities:
+  - format a byte count as a human-readable size string
+```
+
+Those six keys are the minimum. The optional parts carry most of the information: modules with
+interfaces and extraction notes, evidence anyone can rerun, and records of what was reused from
+where. [spec/SPEC.md](spec/SPEC.md) defines every field, puts a length limit on every string,
+and sets out how to read a stranger's manifest safely.
+
+Only permissively licensed projects qualify (MIT, Apache-2.0, the BSDs and similar), so
+anything listed can be reused without asking.
+
+## Get started
+
+- **Claude Code:** `/plugin marketplace add jbmv/recx`, then `/plugin install recx@recx`
+  (or, on Claude Code 2.1.275 or later, `/plugin install recx --marketplace jbmv/recx`). Then
+  ask Claude to add a RECX.yaml. A Stop hook keeps the manifest valid; set
+  `RECX_STOP_HOOK=warn` or `off` to soften or disable it.
+- **Any other agent:** paste the prompt in [ADOPT.md](ADOPT.md).
+- **By hand:** start from the example above, then run `uvx --from recx-cli recx check`.
+
+## What's here
+
+| | |
+|---|---|
+| [spec/](spec/) | The spec, its JSON Schema, and valid and invalid example manifests |
+| `recx-cli` on PyPI | `recx check`, the validator (`pip install recx-cli`) |
+| `@jbmv/recx` on npm | The schema and examples, for JavaScript tooling |
+| [plugin/](plugin/) | The Claude Code plugin; this repository is its marketplace |
+| [RECX.yaml](RECX.yaml) | recx's own manifest |
+
+## Status
+
+Experimental. The spec is a v0.1 draft and may change before 1.0; every manifest states the
+version it was written against. `recx check` enforces the whole spec except rule 4, that the
+license file matches `license`. The manifest, the validator and the plugin exist; search, the
+second part described above, is not built yet.
+
+## Kyosei
+
+I built recx for Kyosei, a record-keeping tool for running projects with coding agents. Kyosei
+isn't public yet. It will generate its own RECX.yaml from its records. Nothing in the spec
+depends on Kyosei: it is one client of the spec, like any other tool.
+
+## License
+
+MIT

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "recx-cli"
-version = "0.0.1"
+version = "0.0.3"
 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.3}/spec/SPEC.md

@@ -7,11 +7,11 @@ written against, so a change never silently reinterprets an old file.
 
 ## Purpose
 
-A great deal of permissively licensed code is being written by people working alone, and much
-of it is never read. recx assumes the reader that will look is another person's coding agent,
-and gives it something to read. `RECX.yaml` says what a repository does, which of its parts can
-be taken on their own, how to take them, and which checks anyone can rerun to see that they
-work.
+recx is meant to let coding agents find and evaluate reusable code from solo and small-team
+projects, which are otherwise difficult to discover among the volume of new repositories.
+`RECX.yaml` states, in a fixed machine-readable form, what a repository does, which of its parts
+can be taken on their own, how to take them, and which checks anyone can rerun to confirm that
+they work.
 
 It complements `AGENTS.md` rather than replacing it. `AGENTS.md` tells an agent how to work
 *inside* a repository. `RECX.yaml` tells an agent working somewhere else what it can take

{recx_cli-0.0.1 → recx_cli-0.0.3}/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.3}/src/recx_cli/cli.py

@@ -1,4 +1,4 @@
-"""Command line: `recx check [PATH] [--no-repo]`."""
+"""Command line: `recx check`, `recx evidence`, `recx hook stop`."""
 
 from __future__ import annotations
 
@@ -7,7 +7,9 @@ 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
+from recx_cli.evidence import HELP as EVIDENCE_HELP
+from recx_cli.evidence import evidence
 
 
 def _version() -> str:
@@ -45,11 +47,46 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="skip the checks that look at the repository (rule 3: module paths exist)",
     )
+    ev = sub.add_parser(
+        "evidence",
+        help="run a manifest's evidence commands (your own repository or a sandbox only)",
+        description=EVIDENCE_HELP,
+    )
+    ev.add_argument(
+        "path",
+        nargs="?",
+        default="RECX.yaml",
+        metavar="PATH",
+        help="a manifest file, or a directory holding RECX.yaml (default: ./RECX.yaml)",
+    )
+    ev.add_argument(
+        "--list", action="store_true", help="print each selected entry's commands without running anything"
+    )
+    ev.add_argument("--only", nargs="+", metavar="ID", help="run only the named evidence entries")
+    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()
+    if args.command == "evidence":
+        return evidence(args.path, args.list, args.only)
     target = Path(args.path)
     if target.is_dir():
         target = target / "RECX.yaml"
@@ -63,5 +100,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.3/src/recx_cli/evidence.py

@@ -0,0 +1,77 @@
+"""`recx evidence`: run a manifest's own evidence commands, in the repository owner's CI."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from recx_cli.check import Unreadable, check_file, format_problem, parse
+
+HELP = (
+    "Run each evidence entry's setup and run commands (sh -c, from the manifest's directory, "
+    "with your environment) and report pass or fail. This runs the manifest's commands: use it "
+    "on your own repository or inside a sandbox, never on a stranger's manifest outside one "
+    "(SPEC, Trust). The manifest must pass `recx check` first. "
+    "Exit status: 0 all selected entries passed, 1 an entry failed or the manifest is invalid, "
+    "2 usage error or unreadable file."
+)
+
+
+def _run(command: str, cwd: Path) -> int:
+    sys.stdout.flush()
+    sys.stderr.flush()
+    return subprocess.run(["sh", "-c", command], cwd=cwd).returncode
+
+
+def evidence(path: str, list_only: bool = False, only: list[str] | None = None) -> int:
+    target = Path(path)
+    if target.is_dir():
+        target = target / "RECX.yaml"
+    label = str(target)
+    try:
+        problems = check_file(target, repo=True)
+    except Unreadable as exc:
+        print(f"{label}: cannot read: {exc}", file=sys.stderr)
+        return 2
+    if problems:
+        for p in problems:
+            print(format_problem(label, p))
+        return 1
+    entries = parse(target.read_text(encoding="utf-8")).get("evidence") or []
+    if only:
+        known = [e["id"] for e in entries]
+        unknown = [i for i in only if i not in known]
+        if unknown:
+            print(
+                f"recx evidence: no evidence entry with id {', '.join(unknown)} "
+                f"(known: {', '.join(known) or 'none'})",
+                file=sys.stderr,
+            )
+            return 2
+        entries = [e for e in entries if e["id"] in only]
+    if list_only:
+        for e in entries:
+            print(e["id"])
+            if "setup" in e:
+                print(f"  setup: {e['setup']}")
+            print(f"  run: {e['run']}")
+        return 0
+    cwd = target.resolve().parent
+    failed = False
+    for e in entries:
+        start = time.monotonic()
+        code = 0
+        for step in ("setup", "run"):
+            if step in e:
+                code = _run(e[step], cwd)
+                if code != 0:
+                    break
+        secs = f"{time.monotonic() - start:.1f}s"
+        if code == 0:
+            print(f"{e['id']}: pass ({secs})", flush=True)
+        else:
+            failed = True
+            print(f"{e['id']}: fail ({secs}, exit {code})", flush=True)
+    return 1 if failed else 0

recx_cli-0.0.3/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.3}/tests/test_check.py

@@ -238,8 +238,9 @@ 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"))
+    version = __import__("tomllib").loads((ROOT / "pyproject.toml").read_text())["project"]["version"]
+    wheels = list(out.glob(f"recx_cli-{version}-*.whl"))
+    sdists = list(out.glob(f"recx_cli-{version}.tar.gz"))
     assert len(wheels) == 1 and len(sdists) == 1
     with zipfile.ZipFile(wheels[0]) as z:
         names = z.namelist()

recx_cli-0.0.3/tests/test_evidence.py

@@ -0,0 +1,137 @@
+import re
+
+from recx_cli.cli import main
+
+HEAD = """recx: "0.1"
+name: example
+summary: An example project.
+license: MIT
+status: experimental
+capabilities:
+  - do a thing
+modules:
+  - id: m
+    path: RECX.yaml
+    summary: The manifest.
+    interface:
+      type: other
+      entrypoints: ["x"]
+    extract:
+      method: copy
+evidence:
+"""
+
+
+def manifest(tmp_path, body):
+    body = body.replace("    summary: s\n", "    summary: s\n    covers: [m]\n")
+    (tmp_path / "RECX.yaml").write_text(HEAD + body)
+    return tmp_path
+
+
+def run(capsys, *argv):
+    code = main(list(argv))
+    out = capsys.readouterr()
+    return code, out.out, out.err
+
+
+def test_runs_setup_then_run_in_order_from_manifest_dir(tmp_path, capsys, monkeypatch):
+    d = manifest(
+        tmp_path,
+        "  - id: first\n    summary: s\n    setup: echo setup >> log\n    run: echo first >> log\n"
+        "  - id: second\n    summary: s\n    run: echo second >> log\n",
+    )
+    monkeypatch.chdir(tmp_path.parent)  # not the manifest dir
+    code, out, _ = run(capsys, "evidence", str(d))
+    assert code == 0
+    assert (d / "log").read_text().split() == ["setup", "first", "second"]
+    lines = out.strip().splitlines()
+    assert re.fullmatch(r"first: pass \(\d+\.\d+s\)", lines[0])
+    assert re.fullmatch(r"second: pass \(\d+\.\d+s\)", lines[1])
+
+
+def test_command_output_streams_through(tmp_path, capfd):
+    d = manifest(tmp_path, "  - id: a\n    summary: s\n    run: echo hello-from-child\n")
+    assert main(["evidence", str(d)]) == 0
+    assert "hello-from-child" in capfd.readouterr().out
+
+
+def test_failure_reports_exit_code_and_exits_1(tmp_path, capsys):
+    d = manifest(
+        tmp_path,
+        "  - id: bad\n    summary: s\n    run: exit 3\n"
+        "  - id: good\n    summary: s\n    run: 'true'\n",
+    )
+    code, out, _ = run(capsys, "evidence", str(d / "RECX.yaml"))
+    assert code == 1
+    lines = out.strip().splitlines()
+    assert re.fullmatch(r"bad: fail \(\d+\.\d+s, exit 3\)", lines[0])
+    assert lines[1].startswith("good: pass")
+
+
+def test_failed_setup_skips_run(tmp_path, capsys):
+    d = manifest(
+        tmp_path,
+        "  - id: a\n    summary: s\n    setup: exit 4\n    run: touch ran\n",
+    )
+    code, out, _ = run(capsys, "evidence", str(d))
+    assert code == 1
+    assert "a: fail" in out and "exit 4" in out
+    assert not (d / "ran").exists()
+
+
+def test_list_prints_commands_and_runs_nothing(tmp_path, capsys):
+    d = manifest(
+        tmp_path,
+        "  - id: a\n    summary: s\n    setup: touch ran\n    run: touch ran2\n",
+    )
+    code, out, _ = run(capsys, "evidence", str(d), "--list")
+    assert code == 0
+    assert "a" in out and "setup: touch ran" in out and "run: touch ran2" in out
+    assert not (d / "ran").exists() and not (d / "ran2").exists()
+
+
+def test_only_selects_entries(tmp_path, capsys):
+    d = manifest(
+        tmp_path,
+        "  - id: a\n    summary: s\n    run: touch a\n"
+        "  - id: b\n    summary: s\n    run: touch b\n"
+        "  - id: c\n    summary: s\n    run: touch c\n",
+    )
+    code, out, _ = run(capsys, "evidence", str(d), "--only", "c", "a")
+    assert code == 0
+    assert (d / "a").exists() and (d / "c").exists() and not (d / "b").exists()
+    assert [l.split(":")[0] for l in out.strip().splitlines()] == ["a", "c"]
+    code, out, _ = run(capsys, "evidence", str(d), "--list", "--only", "b")
+    assert out.splitlines()[0] == "b" and "a" not in out.split()
+
+
+def test_unknown_only_id_is_usage_error(tmp_path, capsys):
+    d = manifest(tmp_path, "  - id: a\n    summary: s\n    run: touch a\n")
+    code, _, err = run(capsys, "evidence", str(d), "--only", "nope")
+    assert code == 2 and "nope" in err
+    assert not (d / "a").exists()
+
+
+def test_unreadable_file_is_usage_error(tmp_path, capsys):
+    code, _, err = run(capsys, "evidence", str(tmp_path / "missing.yaml"))
+    assert code == 2 and "cannot read" in err
+
+
+def test_invalid_manifest_refuses_and_runs_nothing(tmp_path, capsys):
+    d = manifest(
+        tmp_path,
+        "  - id: a\n    summary: s\n    run: touch ran\n    bogus_field: 1\n",
+    )
+    code, out, _ = run(capsys, "evidence", str(d))
+    assert code == 1
+    assert "bogus_field" in out and "pass" not in out
+    assert not (d / "ran").exists()
+
+
+def test_help_warns_about_strangers(capsys):
+    try:
+        main(["evidence", "--help"])
+    except SystemExit:
+        pass
+    out = capsys.readouterr().out
+    assert "your own repository or inside a sandbox" in " ".join(out.split())

recx_cli-0.0.3/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, "")

recx_cli-0.0.1/PKG-INFO

@@ -1,40 +0,0 @@
-Metadata-Version: 2.5
-Name: recx-cli
-Version: 0.0.1
-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
-Author: James Bullard
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.10
-Requires-Dist: jsonschema[format-nongpl]>=4.18
-Requires-Dist: pyyaml>=6
-Description-Content-Type: text/markdown
-
-# recx
-
-*res extra commercium*: things outside commerce. A repository drops a `RECX.yaml` at its
-root to tell other people's coding agents what it does, which of its modules can be taken on
-their own, how to take them, and which checks anyone can rerun to see that they work.
-
-The format is specified in [spec/SPEC.md](spec/SPEC.md); the schema is
-[spec/recx.schema.json](spec/recx.schema.json).
-
-## Checking a manifest
-
-```sh
-pip install recx-cli          # or: uvx --from recx-cli recx check
-
-recx check                    # ./RECX.yaml, including that module paths exist
-recx check path/to/repo       # a directory holding RECX.yaml
-recx check --no-repo FILE     # the file alone, without looking at the repository
-```
-
-One line per problem, `<file>: <json-pointer>: <message>`, or `<file>: valid`. Exit status 0
-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 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/README.md

@@ -1,26 +0,0 @@
-# recx
-
-*res extra commercium*: things outside commerce. A repository drops a `RECX.yaml` at its
-root to tell other people's coding agents what it does, which of its modules can be taken on
-their own, how to take them, and which checks anyone can rerun to see that they work.
-
-The format is specified in [spec/SPEC.md](spec/SPEC.md); the schema is
-[spec/recx.schema.json](spec/recx.schema.json).
-
-## Checking a manifest
-
-```sh
-pip install recx-cli          # or: uvx --from recx-cli recx check
-
-recx check                    # ./RECX.yaml, including that module paths exist
-recx check path/to/repo       # a directory holding RECX.yaml
-recx check --no-repo FILE     # the file alone, without looking at the repository
-```
-
-One line per problem, `<file>: <json-pointer>: <message>`, or `<file>: valid`. Exit status 0
-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 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.