claude-dev-env 1.26.5 → 1.27.0

package/hooks/git-hooks/pre_push.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Git pre-push hook: run the CODE_RULES gate over commits about to be pushed.
+
+Installed to the user's shared git-hooks directory via the claude-dev-env
+installer; git invokes this file as `pre-push` (the installer strips the
+`_` and `.py` suffix when copying into the live hooks path).
+
+Protocol: git pre-push provides remote name and URL as argv, then writes
+`<local-ref> <local-sha> <remote-ref> <remote-sha>` lines on stdin. The
+first non-zero remote-sha is used as the gate `--base`, so violations are
+scoped to commits that are not already on the remote. When every remote
+object name is zero (new branch) or stdin is empty, the gate falls back
+to the remote's default branch symbolic ref.
+
+Exit codes:
+  0 - commits to be pushed pass the gate (or the gate is not installed).
+  1 - one or more commits introduce blocking violations.
+  2 - unexpected invocation failure (e.g., subprocess could not launch).
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+from config import (
+    ALL_ZEROS_OBJECT_NAME_CHARACTER,
+    BASE_REFERENCE_ARGUMENT,
+    DEFAULT_REMOTE_BASE_REFERENCE,
+    GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE,
+    INVOKE_GATE_FAILURE_MESSAGE,
+    LOCAL_SHA_FIELD_INDEX,
+    MALFORMED_STDIN_LINE_MESSAGE,
+    NO_PARSEABLE_STDIN_LINES_MESSAGE,
+    NO_PARSEABLE_STDIN_LINES_SENTINEL,
+    PRE_PUSH_GATE_SCRIPT_NOT_FOUND_MESSAGE,
+    STDIN_LINE_FIELD_COUNT,
+    STDIN_READ_FAILURE_MESSAGE,
+    STDIN_REMOTE_OBJECT_FIELD_INDEX,
+)
+from gate_utils import is_safe_regular_file, resolve_gate_script_path
+
+
+def is_all_zeros_object_name(object_name: str) -> bool:
+    all_zeros_object_name_character = ALL_ZEROS_OBJECT_NAME_CHARACTER
+    stripped_object_name = object_name.strip()
+    if not stripped_object_name:
+        return True
+    return all(
+        each_character == all_zeros_object_name_character
+        for each_character in stripped_object_name
+    )
+
+
+def resolve_base_reference_from_stdin(stdin_text: str) -> str | None:
+    stdin_line_field_count = STDIN_LINE_FIELD_COUNT
+    stdin_remote_object_field_index = STDIN_REMOTE_OBJECT_FIELD_INDEX
+    local_sha_field_index = LOCAL_SHA_FIELD_INDEX
+    default_remote_base_reference = DEFAULT_REMOTE_BASE_REFERENCE
+    malformed_stdin_line_message = MALFORMED_STDIN_LINE_MESSAGE
+    has_seen_any_valid_line = False
+    is_all_valid_lines_deletions = True
+    has_stdin_content = False
+    for each_line in stdin_text.splitlines():
+        stripped_line = each_line.strip()
+        if not stripped_line:
+            continue
+        has_stdin_content = True
+        fields = stripped_line.split()
+        if len(fields) < stdin_line_field_count:
+            print(
+                malformed_stdin_line_message.format(line=stripped_line),
+                file=sys.stderr,
+            )
+            continue
+        has_seen_any_valid_line = True
+        if is_all_zeros_object_name(fields[local_sha_field_index]):
+            continue
+        is_all_valid_lines_deletions = False
+        remote_object_name = fields[stdin_remote_object_field_index]
+        if not is_all_zeros_object_name(remote_object_name):
+            return remote_object_name
+    if has_stdin_content and not has_seen_any_valid_line:
+        return NO_PARSEABLE_STDIN_LINES_SENTINEL
+    if has_seen_any_valid_line and is_all_valid_lines_deletions:
+        return None
+    return default_remote_base_reference
+
+
+def invoke_gate(gate_script_path: Path, base_reference: str) -> int:
+    base_reference_argument = BASE_REFERENCE_ARGUMENT
+    invoke_gate_failure_message = INVOKE_GATE_FAILURE_MESSAGE
+    gate_infrastructure_failure_exit_code = GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE
+    try:
+        resolved_gate_path = gate_script_path.resolve(strict=True)
+        completion = subprocess.run(
+            [
+                sys.executable,
+                str(resolved_gate_path),
+                base_reference_argument,
+                base_reference,
+            ],
+            check=False,
+        )
+    except OSError as launch_error:
+        print(
+            invoke_gate_failure_message.format(error=launch_error),
+            file=sys.stderr,
+        )
+        return gate_infrastructure_failure_exit_code
+    return completion.returncode
+
+
+def main() -> int:
+    stdin_read_failure_message = STDIN_READ_FAILURE_MESSAGE
+    gate_infrastructure_failure_exit_code = GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE
+    pre_push_gate_script_not_found_message = PRE_PUSH_GATE_SCRIPT_NOT_FOUND_MESSAGE
+    no_parseable_stdin_lines_message = NO_PARSEABLE_STDIN_LINES_MESSAGE
+    no_parseable_stdin_lines_sentinel = NO_PARSEABLE_STDIN_LINES_SENTINEL
+    gate_script_path, exact_allowed_path = resolve_gate_script_path()
+    if not is_safe_regular_file(gate_script_path, exact_allowed_path):
+        print(
+            pre_push_gate_script_not_found_message.format(path=gate_script_path),
+            file=sys.stderr,
+        )
+        return 0
+    try:
+        stdin_text = sys.stdin.read()
+    except OSError as read_error:
+        print(
+            stdin_read_failure_message.format(error=read_error),
+            file=sys.stderr,
+        )
+        return gate_infrastructure_failure_exit_code
+    base_reference = resolve_base_reference_from_stdin(stdin_text)
+    if base_reference is None:
+        return 0
+    if base_reference == no_parseable_stdin_lines_sentinel:
+        print(no_parseable_stdin_lines_message, file=sys.stderr)
+        return gate_infrastructure_failure_exit_code
+    return invoke_gate(gate_script_path, base_reference)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/git-hooks/test_config.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+SCRIPT_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPT_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIRECTORY))
+
+import config
+
+
+def test_pre_push_gate_script_not_found_message_contains_path_placeholder() -> None:
+    assert "{path}" in config.PRE_PUSH_GATE_SCRIPT_NOT_FOUND_MESSAGE
+
+
+def test_no_parseable_stdin_lines_message_exists_and_describes_problem() -> None:
+    assert "no parseable stdin lines" in config.NO_PARSEABLE_STDIN_LINES_MESSAGE
+
+
+def test_no_parseable_stdin_lines_sentinel_is_distinct_sentinel_value() -> None:
+    assert config.NO_PARSEABLE_STDIN_LINES_SENTINEL is not None
+    assert config.NO_PARSEABLE_STDIN_LINES_SENTINEL != config.DEFAULT_REMOTE_BASE_REFERENCE

package/hooks/git-hooks/test_gate_utils.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+
+SCRIPT_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPT_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIRECTORY))
+
+import gate_utils
+
+
+def test_resolve_gate_script_path_uses_override_env_var_when_set(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    override_path = tmp_path / "override_gate.py"
+    override_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(override_path))
+
+    resolved_path, exact_allowed = gate_utils.resolve_gate_script_path()
+
+    assert resolved_path == override_path
+    assert exact_allowed == override_path
+
+
+def test_resolve_gate_script_path_defaults_to_claude_home_when_env_var_set(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CODE_RULES_GATE_PATH", raising=False)
+    monkeypatch.setenv("CLAUDE_HOME", str(tmp_path))
+
+    resolved_path, exact_allowed = gate_utils.resolve_gate_script_path()
+
+    expected_path = (
+        tmp_path / "skills" / "bugteam" / "scripts" / "bugteam_code_rules_gate.py"
+    )
+    assert resolved_path == expected_path
+    assert exact_allowed is None
+
+
+def test_resolve_gate_script_path_falls_back_to_home_dot_claude_when_no_env_vars(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CODE_RULES_GATE_PATH", raising=False)
+    monkeypatch.delenv("CLAUDE_HOME", raising=False)
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path))
+
+    resolved_path, exact_allowed = gate_utils.resolve_gate_script_path()
+
+    expected_path = (
+        tmp_path
+        / ".claude"
+        / "skills"
+        / "bugteam"
+        / "scripts"
+        / "bugteam_code_rules_gate.py"
+    )
+    assert resolved_path == expected_path
+    assert exact_allowed is None
+
+
+def test_resolve_gate_script_path_resolves_relative_override_to_absolute(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", "relative/gate.py")
+
+    resolved_path, _ = gate_utils.resolve_gate_script_path()
+
+    assert resolved_path.is_absolute()
+
+
+def test_is_safe_regular_file_rejects_sibling_of_override_path(
+    tmp_path: Path,
+) -> None:
+    override_gate = tmp_path / "gate.py"
+    override_gate.write_text("", encoding="utf-8")
+    sibling_script = tmp_path / "attacker_script.py"
+    sibling_script.write_text("", encoding="utf-8")
+
+    is_safe = gate_utils.is_safe_regular_file(sibling_script, override_gate.resolve())
+
+    assert not is_safe
+
+
+def test_is_safe_regular_file_accepts_exact_override_path(
+    tmp_path: Path,
+) -> None:
+    override_gate = tmp_path / "gate.py"
+    override_gate.write_text("", encoding="utf-8")
+
+    is_safe = gate_utils.is_safe_regular_file(override_gate, override_gate.resolve())
+
+    assert is_safe
+
+
+def test_is_safe_regular_file_rejects_claude_home_override_outside_home_dot_claude(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    attacker_home = tmp_path / "attacker_home"
+    gate_under_attacker_home = (
+        attacker_home / "skills" / "bugteam" / "scripts" / "bugteam_code_rules_gate.py"
+    )
+    gate_under_attacker_home.parent.mkdir(parents=True)
+    gate_under_attacker_home.write_text("", encoding="utf-8")
+    real_home = tmp_path / "real_home"
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: real_home))
+
+    is_safe = gate_utils.is_safe_regular_file(gate_under_attacker_home, None)
+
+    assert not is_safe
+
+
+def test_is_safe_regular_file_accepts_gate_inside_home_dot_claude(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    home_dir = tmp_path / "real_home"
+    gate_path = (
+        home_dir / ".claude" / "skills" / "bugteam" / "scripts" / "bugteam_code_rules_gate.py"
+    )
+    gate_path.parent.mkdir(parents=True)
+    gate_path.write_text("", encoding="utf-8")
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: home_dir))
+
+    is_safe = gate_utils.is_safe_regular_file(gate_path, None)
+
+    assert is_safe
+
+
+def test_is_safe_regular_file_rejects_nonexistent_path_under_trusted_prefix(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    home_dir = tmp_path / "real_home"
+    (home_dir / ".claude").mkdir(parents=True)
+    missing_gate_path = (
+        home_dir / ".claude" / "skills" / "bugteam" / "scripts" / "missing_gate.py"
+    )
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: home_dir))
+
+    is_safe = gate_utils.is_safe_regular_file(missing_gate_path, None)
+
+    assert not is_safe
+
+
+def test_is_safe_regular_file_resolves_symlink_before_prefix_check(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    home_dir = tmp_path / "home"
+    claude_home = home_dir / ".claude"
+    claude_home.mkdir(parents=True)
+    real_target = tmp_path / "outside_claude" / "evil.py"
+    real_target.parent.mkdir(parents=True)
+    real_target.write_text("", encoding="utf-8")
+    symlink_inside_claude = claude_home / "evil_link.py"
+    symlink_inside_claude.symlink_to(real_target)
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: home_dir))
+
+    is_safe = gate_utils.is_safe_regular_file(symlink_inside_claude, None)
+
+    assert not is_safe
+
+
+def test_is_safe_regular_file_uses_claude_home_env_as_trust_root(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    custom_claude_home = tmp_path / "custom_claude"
+    gate_path = (
+        custom_claude_home / "skills" / "bugteam" / "scripts" / "bugteam_code_rules_gate.py"
+    )
+    gate_path.parent.mkdir(parents=True)
+    gate_path.write_text("", encoding="utf-8")
+    monkeypatch.delenv("CODE_RULES_GATE_PATH", raising=False)
+    monkeypatch.setenv("CLAUDE_HOME", str(custom_claude_home))
+
+    gate_script_path, exact_allowed = gate_utils.resolve_gate_script_path()
+
+    is_safe = gate_utils.is_safe_regular_file(gate_script_path, exact_allowed)
+
+    assert is_safe
+
+
+def test_resolve_gate_script_path_snapshot_is_consistent_with_is_safe_regular_file(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    custom_claude_home = tmp_path / "custom_claude"
+    gate_path = (
+        custom_claude_home / "skills" / "bugteam" / "scripts" / "bugteam_code_rules_gate.py"
+    )
+    gate_path.parent.mkdir(parents=True)
+    gate_path.write_text("", encoding="utf-8")
+    monkeypatch.delenv("CODE_RULES_GATE_PATH", raising=False)
+    monkeypatch.setenv("CLAUDE_HOME", str(custom_claude_home))
+
+    resolved_path, exact_allowed = gate_utils.resolve_gate_script_path()
+    is_safe = gate_utils.is_safe_regular_file(resolved_path, exact_allowed)
+
+    assert is_safe
+
+
+def test_is_safe_regular_file_rejects_path_outside_claude_home_env_trust_root(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    custom_claude_home = tmp_path / "custom_claude"
+    custom_claude_home.mkdir(parents=True)
+    outside_path = tmp_path / "outside" / "gate.py"
+    outside_path.parent.mkdir(parents=True)
+    outside_path.write_text("", encoding="utf-8")
+    monkeypatch.delenv("CODE_RULES_GATE_PATH", raising=False)
+    monkeypatch.setenv("CLAUDE_HOME", str(custom_claude_home))
+
+    is_safe = gate_utils.is_safe_regular_file(outside_path, None)
+
+    assert not is_safe

package/hooks/git-hooks/test_pre_commit.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+
+SCRIPT_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPT_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIRECTORY))
+
+import pre_commit
+
+
+def make_gate_script_returning(exit_code: int, target_path: Path) -> Path:
+    target_path.write_text(
+        f"import sys\nsys.exit({exit_code})\n",
+        encoding="utf-8",
+    )
+    return target_path
+
+
+@pytest.fixture()
+def fake_gate_script_blocking(tmp_path: Path) -> Path:
+    return make_gate_script_returning(1, tmp_path / "fake_gate_blocking.py")
+
+
+@pytest.fixture()
+def fake_gate_script_passing(tmp_path: Path) -> Path:
+    return make_gate_script_returning(0, tmp_path / "fake_gate_passing.py")
+
+
+def test_main_exits_zero_when_gate_script_missing(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv(
+        "CODE_RULES_GATE_PATH",
+        str(tmp_path / "does_not_exist.py"),
+    )
+
+    exit_code = pre_commit.main()
+
+    assert exit_code == 0
+
+
+def test_main_propagates_blocking_exit_code_from_gate(
+    fake_gate_script_blocking: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(fake_gate_script_blocking))
+
+    exit_code = pre_commit.main()
+
+    assert exit_code == 1
+
+
+def test_main_propagates_passing_exit_code_from_gate(
+    fake_gate_script_passing: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(fake_gate_script_passing))
+
+    exit_code = pre_commit.main()
+
+    assert exit_code == 0
+
+
+def test_main_invokes_gate_with_staged_flag(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    recorded_arguments_path = tmp_path / "recorded_arguments.txt"
+    recording_gate_script_path = tmp_path / "recording_gate.py"
+    recording_gate_script_path.write_text(
+        "import sys, pathlib\n"
+        f'pathlib.Path(r"{recorded_arguments_path}").write_text('
+        "'\\n'.join(sys.argv[1:]), encoding='utf-8')\n"
+        "sys.exit(0)\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(recording_gate_script_path))
+
+    exit_code = pre_commit.main()
+
+    assert exit_code == 0
+    assert recorded_arguments_path.exists(), (
+        f"recording gate did not write to {recorded_arguments_path}"
+    )
+    recorded_arguments = recorded_arguments_path.read_text(
+        encoding="utf-8"
+    ).splitlines()
+    assert recorded_arguments == ["--staged"]
+
+
+def test_main_exits_two_when_invoke_gate_raises_oserror(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    existing_gate_path = tmp_path / "gate.py"
+    existing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(existing_gate_path))
+
+    original_run = __import__("subprocess").run
+
+    def raising_run(*args: object, **kwargs: object) -> object:
+        raise OSError("no such file")
+
+    monkeypatch.setattr(__import__("subprocess"), "run", raising_run)
+
+    exit_code = pre_commit.main()
+
+    assert exit_code == 2
+
+
+def test_main_emits_stderr_warning_when_gate_script_missing(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setenv(
+        "CODE_RULES_GATE_PATH",
+        str(tmp_path / "does_not_exist.py"),
+    )
+
+    exit_code = pre_commit.main()
+
+    assert exit_code == 0
+    captured = capsys.readouterr()
+    assert "gate script not found" in captured.err
+
+
+def test_invoke_gate_returns_infrastructure_failure_when_strict_resolve_raises(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    missing_gate_path = tmp_path / "missing_gate.py"
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(missing_gate_path))
+    missing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+
+    original_resolve = Path.resolve
+
+    def raising_resolve(self: Path, strict: bool = False) -> Path:
+        if strict and self == missing_gate_path.resolve():
+            raise FileNotFoundError("not found")
+        return original_resolve(self, strict=strict)
+
+    monkeypatch.setattr(Path, "resolve", raising_resolve)
+
+    exit_code = pre_commit.invoke_gate(missing_gate_path)
+
+    assert exit_code == 2
+
+
+def test_invoke_gate_uses_resolved_path(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    real_gate_dir = tmp_path / "real"
+    real_gate_dir.mkdir()
+    real_gate_path = real_gate_dir / "gate.py"
+    recorded_path_file = tmp_path / "recorded_path.txt"
+    real_gate_path.write_text(
+        "import sys, pathlib\n"
+        f'pathlib.Path(r"{recorded_path_file}").write_text(sys.argv[0], encoding="utf-8")\n'
+        "sys.exit(0)\n",
+        encoding="utf-8",
+    )
+    symlink_gate_path = tmp_path / "link_gate.py"
+    symlink_gate_path.symlink_to(real_gate_path)
+    resolved_path = symlink_gate_path.resolve()
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(symlink_gate_path))
+
+    exit_code = pre_commit.main()
+
+    assert exit_code == 0
+    executed_path = recorded_path_file.read_text(encoding="utf-8")
+    assert executed_path == str(resolved_path)