claude-dev-env 1.23.1 → 1.25.0

package/hooks/blocking/gh-body-arg-blocker.py

@@ -14,19 +14,20 @@ logical line, then use shlex.split(..., posix=False) on that line so '--body'
 appearing inside a quoted flag value or in heredoc body content on non-continuation
 lines does not trigger a false positive. Both '--body value' and '--body=value' forms are blocked,
 as are their short '-b' equivalents. '--body-file' and '--body-file=...' are allowed.
-Falls back to a conservative approve if the logical line is unparseable.
+Fails CLOSED on shlex ValueError when the logical line matches an affected
+subcommand AND contains a bare '--body'/'-b' literal (exactly the heredoc
+pattern this hook must catch); otherwise approves unparseable input.
 """
 
 import json
 import re
-import shlex
 import sys
 
 from _gh_body_arg_utils import (
     all_body_flags,
     all_body_flag_prefixes,
-    all_value_flags,
     get_logical_first_line,
+    iter_significant_tokens,
 )
 
 _GH_BODY_SUBCOMMANDS = re.compile(
@@ -37,6 +38,10 @@ _GH_BODY_SUBCOMMANDS = re.compile(
     re.IGNORECASE,
 )
 
+_BARE_BODY_TOKEN_PATTERN = re.compile(
+    r"(?<!\S)(?:--body|-b)(?:=|(?![-\w]))",
+)
+
 _BASH_TOOL_NAME = "Bash"
 
 _CORRECTIVE_MESSAGE = (
@@ -49,16 +54,21 @@ _CORRECTIVE_MESSAGE = (
     "      f.write(body_text)\n"
     "      body_path = f.name\n"
     "  # then: gh ... --body-file body_path\n\n"
-    "Safe PowerShell pattern:\n"
+    "Safe PowerShell pattern (BOM-free, works on 5.1 and 7+):\n"
     "  $bodyPath = [System.IO.Path]::ChangeExtension((New-TemporaryFile).FullName, '.md')\n"
-    "  @'\n"
+    "  $body = @'\n"
     "  <your markdown body>\n"
-    "  '@ | Set-Content -Path $bodyPath -Encoding utf8\n"
+    "  '@\n"
+    "  [IO.File]::WriteAllText($bodyPath, $body, [Text.UTF8Encoding]::new($false))\n"
     "  gh ... --body-file $bodyPath\n\n"
     "See ~/.claude/rules/gh-body-file.md for full guidance."
 )
 
 
+def _logical_line_has_bare_body_token(logical_line: str) -> bool:
+    return bool(_BARE_BODY_TOKEN_PATTERN.search(logical_line))
+
+
 def _uses_body_string_arg(command: str) -> bool:
     """Return True if command calls an affected gh subcommand with --body <string>.
 
@@ -68,26 +78,22 @@ def _uses_body_string_arg(command: str) -> bool:
     and quoted values retain their surrounding quotes as part of the token, so
     '--body' embedded in a quoted value cannot be mistaken for a standalone flag.
     Detects both '--body value'/'--body=value' forms and their short '-b'
-    equivalents. Falls back to a conservative approve if the line is unparseable.
+    equivalents. Fails CLOSED on shlex ValueError when the logical line matches
+    an affected subcommand and contains a bare --body / -b token literal, since
+    heredoc-wrapped --body arguments are exactly the pattern this hook exists
+    to block; otherwise approves unparseable input (out of scope).
     """
-    logical_line = get_logical_first_line(command)
-    if not _GH_BODY_SUBCOMMANDS.search(logical_line):
+    if not _GH_BODY_SUBCOMMANDS.search(get_logical_first_line(command)):
         return False
     try:
-        tokens = shlex.split(logical_line, posix=False)
+        significant_tokens = list(iter_significant_tokens(command))
     except ValueError:
-        return False
-    should_skip_next_token = False
-    for each_token in tokens:
-        if should_skip_next_token:
-            should_skip_next_token = False
-            continue
-        if each_token in all_body_flags or any(
-            each_token.startswith(each_prefix) for each_prefix in all_body_flag_prefixes
-        ):
+        return _logical_line_has_bare_body_token(get_logical_first_line(command))
+    for each_token, _remaining_tokens in significant_tokens:
+        if each_token in all_body_flags:
+            return True
+        if any(each_token.startswith(each_prefix) for each_prefix in all_body_flag_prefixes):
             return True
-        if each_token in all_value_flags:
-            should_skip_next_token = True
     return False
 
 

package/hooks/blocking/pr-description-enforcer.py

@@ -2,6 +2,23 @@ import json
 import os
 import re
 import sys
+from pathlib import Path
+
+import shlex
+
+from _gh_body_arg_utils import (
+    all_body_flag_prefixes,
+    all_body_flags,
+    all_value_flag_equals_prefixes,
+    all_value_flags,
+    body_file_flag,
+    body_file_flag_prefix,
+    body_file_short_flag,
+    body_file_short_flag_prefix,
+    count_extra_tokens_to_skip_for_split_quoted_value,
+    get_logical_first_line,
+    iter_significant_tokens,
+)
 
 PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 PR_GUIDE_PATH = os.path.join(PLUGIN_ROOT, "docs", "PR_DESCRIPTION_GUIDE.md")
@@ -20,20 +37,236 @@ VAGUE_LANGUAGE_PATTERN = re.compile(
 )
 
 
-def extract_body_from_command(command: str) -> str:
-    heredoc_match = re.search(r'--body\s+"\$\(cat <<', command)
-    if heredoc_match:
-        return command[heredoc_match.start():]
+shell_variable_sigil: str = "$"
+body_file_stdin_sentinel: str = "-"
+all_quote_characters: frozenset[str] = frozenset({'"', "'"})
+file_encoding_utf8: str = "utf-8"
+
+_non_body_value_flags: frozenset[str] = all_value_flags - {body_file_flag, body_file_short_flag}
+
+_non_body_value_flag_equals_prefixes: tuple[str, ...] = tuple(
+    sorted(
+        (
+            prefix for prefix in all_value_flag_equals_prefixes
+            if not prefix.startswith("--body") and not prefix.startswith("-b=")
+        ),
+        key=len,
+        reverse=True,
+    )
+)
+
+
+class PathTraversalError(Exception):
+    pass
+
+def _is_flag_shaped_token(token: str) -> bool:
+    if len(token) < 2:
+        return False
+    if not token.startswith("-"):
+        return False
+    return token[1] == "-" or token[1].isalpha()
+
+
+def _strip_surrounding_quotes(token: str) -> str:
+    if len(token) < 2:
+        return token
+    first_character = token[0]
+    last_character = token[-1]
+    if first_character in all_quote_characters and first_character == last_character:
+        return token[1:-1]
+    return token
+
+
+def _is_unresolvable_shell_value(token: str) -> bool:
+    return token.startswith(shell_variable_sigil)
+
+
+def _read_body_file_contents(file_path: str) -> str | None:
+    given_path = Path(file_path)
+    allowed_root = Path.cwd().resolve()
+    if given_path.is_symlink():
+        resolved_target = given_path.resolve()
+        try:
+            resolved_target.relative_to(allowed_root)
+        except ValueError:
+            raise PathTraversalError("symlink target resolves outside allowed root")
+    resolved_path = given_path.resolve()
+    if not given_path.is_absolute():
+        try:
+            resolved_path.relative_to(allowed_root)
+        except ValueError:
+            raise PathTraversalError("relative path resolves outside allowed root")
+    try:
+        with open(resolved_path, "r", encoding=file_encoding_utf8, errors="replace") as body_file:
+            return body_file.read()
+    except (FileNotFoundError, IsADirectoryError, PermissionError, OSError):
+        return None
+
+
+def _resolve_body_file_value(raw_value_token: str) -> str | None:
+    """Return file contents, or None when the body cannot be audited.
+
+    None means body is present but unauditable -- skip enforcement.
+    This covers: stdin sentinel, unresolvable shell variables, and path-traversal-rejected paths.
+    """
+    stripped_value = _strip_surrounding_quotes(raw_value_token)
+    if not stripped_value:
+        return None
+    if stripped_value == body_file_stdin_sentinel:
+        return None
+    if _is_unresolvable_shell_value(stripped_value):
+        return None
+    try:
+        return _read_body_file_contents(stripped_value)
+    except PathTraversalError:
+        return None
+
+
+def _resolve_body_string_value(raw_value_token: str) -> str:
+    stripped_value = _strip_surrounding_quotes(raw_value_token)
+    if _is_unresolvable_shell_value(stripped_value):
+        return ""
+    return stripped_value
+
+
+def _reassemble_split_quoted_value(first_value_token: str, remaining_tokens: list[str]) -> str | None:
+    extra_tokens_consumed = count_extra_tokens_to_skip_for_split_quoted_value(
+        remaining_tokens,
+        first_value_token,
+    )
+    if extra_tokens_consumed is None:
+        return None
+    if extra_tokens_consumed == 0:
+        return first_value_token
+    continuation_tokens = remaining_tokens[:extra_tokens_consumed]
+    return " ".join([first_value_token, *continuation_tokens])
+
+
+def _match_body_flag_equals_prefix(token: str) -> str | None:
+    for each_prefix in all_body_flag_prefixes:
+        if token.startswith(each_prefix):
+            return each_prefix
+    return None
+
+
+def _match_body_file_equals_prefix(token: str) -> str | None:
+    for each_prefix in (body_file_flag_prefix, body_file_short_flag_prefix):
+        if token.startswith(each_prefix):
+            return each_prefix
+    return None
+
+
+def _match_non_body_value_flag_equals_prefix(token: str) -> str | None:
+    for each_prefix in _non_body_value_flag_equals_prefixes:
+        if token.startswith(each_prefix):
+            return each_prefix
+    return None
 
-    body_match = re.search(r'--body\s+"([^"]*)"', command) or re.search(r"--body\s+'([^']*)'", command)
-    if body_match:
-        return body_match.group(1)
 
-    short_flag_match = re.search(r'-b\s+"([^"]*)"', command) or re.search(r"-b\s+'([^']*)'", command)
-    if short_flag_match:
-        return short_flag_match.group(1)
+def _scan_raw_tokens_for_body(all_raw_tokens: list[str]) -> str | None | bool:
+    """Return the body value from a raw token list, or False if no body flag found.
 
-    return ""
+    Returns False when no body/body-file flag is present (caller should continue).
+    Returns None when a body-file flag is present but malformed (no value follows).
+    Returns str for body string values (may be empty for shell vars/sentinels).
+    """
+    token_index = 0
+    while token_index < len(all_raw_tokens):
+        current_token = all_raw_tokens[token_index]
+        remaining_raw = all_raw_tokens[token_index + 1:]
+        non_body_equals_prefix = _match_non_body_value_flag_equals_prefix(current_token)
+        if non_body_equals_prefix is not None:
+            first_value_token = current_token[len(non_body_equals_prefix):]
+            extra_skip = count_extra_tokens_to_skip_for_split_quoted_value(remaining_raw, first_value_token)
+            token_index += 1 + (extra_skip or 0)
+            continue
+        if current_token in _non_body_value_flags:
+            if remaining_raw and not _is_flag_shaped_token(remaining_raw[0]):
+                first_value_token = remaining_raw[0]
+                extra_skip = count_extra_tokens_to_skip_for_split_quoted_value(remaining_raw[1:], first_value_token)
+                token_index += 1 + 1 + (extra_skip or 0)
+                continue
+            token_index += 1
+            continue
+        body_equals_prefix = _match_body_flag_equals_prefix(current_token)
+        if body_equals_prefix is not None:
+            first_value_token = current_token[len(body_equals_prefix):]
+            full_value_token = _reassemble_split_quoted_value(first_value_token, remaining_raw)
+            if full_value_token is None:
+                return None
+            return _resolve_body_string_value(full_value_token)
+        body_file_equals_prefix = _match_body_file_equals_prefix(current_token)
+        if body_file_equals_prefix is not None:
+            first_value_token = current_token[len(body_file_equals_prefix):]
+            full_value_token = _reassemble_split_quoted_value(first_value_token, remaining_raw)
+            if full_value_token is None:
+                return None
+            return _resolve_body_file_value(full_value_token)
+        if current_token in all_body_flags:
+            if not remaining_raw or _is_flag_shaped_token(remaining_raw[0]):
+                return None
+            first_value_token = remaining_raw[0]
+            full_value_token = _reassemble_split_quoted_value(first_value_token, remaining_raw[1:])
+            if full_value_token is None:
+                return None
+            return _resolve_body_string_value(full_value_token)
+        if current_token in {body_file_flag, body_file_short_flag}:
+            if not remaining_raw or _is_flag_shaped_token(remaining_raw[0]):
+                return None
+            first_value_token = remaining_raw[0]
+            full_value_token = _reassemble_split_quoted_value(first_value_token, remaining_raw[1:])
+            if full_value_token is None:
+                return None
+            return _resolve_body_file_value(full_value_token)
+        token_index += 1
+    return False
+
+
+def extract_body_from_command(
+    command: str,
+    pre_tokenized: tuple[str, list[str]] | None = None,
+) -> str | None:
+    """Return the PR body content for validation, or None if unextractable.
+
+    Uses iter_significant_tokens to skip values of non-body value-taking flags
+    so that --body/--body-file embedded in a quoted --title value never false-matches.
+    For space-form body-file flags, scans the raw token list directly because
+    iter_significant_tokens consumes the value token (yielding remaining-after-value).
+
+    If pre_tokenized is provided as (logical_line, raw_tokens), reuses those instead
+    of recomputing the logical line and shlex split a second time.
+    """
+    if pre_tokenized is not None:
+        logical_line, all_raw_tokens = pre_tokenized
+    else:
+        logical_line = get_logical_first_line(command)
+        if not logical_line:
+            return None
+        try:
+            all_raw_tokens = shlex.split(logical_line, posix=False)
+        except ValueError:
+            return None
+    try:
+        all_significant_tokens = list(
+            iter_significant_tokens(command, pre_tokenized=(logical_line, all_raw_tokens))
+        )
+    except ValueError:
+        return None
+
+    significant_token_set = {each_token for each_token, _ in all_significant_tokens}
+    body_flag_found_in_significant = (
+        any(each_token in all_body_flags for each_token in significant_token_set)
+        or any(_match_body_flag_equals_prefix(each_token) is not None for each_token in significant_token_set)
+        or any(_match_body_file_equals_prefix(each_token) is not None for each_token in significant_token_set)
+        or any(each_token in {body_file_flag, body_file_short_flag} for each_token in significant_token_set)
+    )
+    if not body_flag_found_in_significant:
+        return None
+
+    result = _scan_raw_tokens_for_body(all_raw_tokens)
+    if result is False:
+        return None
+    return result
 
 
 def validate_pr_body(body: str) -> list[str]:
@@ -83,6 +316,9 @@ def main() -> None:
 
     body = extract_body_from_command(command)
 
+    if body is None:
+        sys.exit(0)
+
     if not body:
         sys.exit(0)
 

package/hooks/blocking/tdd-enforcer.py

@@ -1,12 +1,15 @@
 #!/usr/bin/env python3
 """
-BDD Automate-phase reminder (production code touch).
+BDD Automate-phase gate (production code touch).
 
-Prompts confirmation when writing or editing production code files.
-Skips: Test files, config files, documentation.
+Blocks writes to production source files when no matching test exists
+or the matching test has not been modified within the configured
+freshness window. Enforces "TDD IS NON-NEGOTIABLE" from CLAUDE.md.
 """
 import json
+import re
 import sys
+import time
 from pathlib import Path
 
 PRODUCTION_EXTENSIONS = {'.py', '.ts', '.tsx', '.js', '.jsx'}
@@ -17,12 +20,201 @@ SKIP_PATTERNS = {
 SKIP_EXTENSIONS = {'.md', '.json', '.yaml', '.yml', '.toml', '.ini', '.cfg', '.txt'}
 
 
+def _freshness_seconds() -> int:
+    return 600
+
+
+def _bypass_sentinel() -> str:
+    return "# pragma: no-tdd-gate"
+
+
+def _tests_directory_name() -> str:
+    return "tests"
+
+
+def _parent_walk_limit() -> int:
+    return 10
+
+
+def _repo_boundary_sentinels() -> frozenset[str]:
+    return frozenset({".git", "pyproject.toml", "package.json", "Cargo.toml", "go.mod"})
+
+
+def _test_function_patterns() -> tuple[re.Pattern[str], ...]:
+    return (
+        re.compile(r"\bdef\s+test_"),
+        re.compile(r"\b(?:it|test|describe)\s*\("),
+    )
+
+
+def _directory_skip_components() -> frozenset[str]:
+    return frozenset({
+        "conftest", "fixture", "fixtures", "mock", "mocks", "stub", "stubs",
+    })
+
+
+def _is_repo_boundary(candidate_directory: Path) -> bool:
+    for each_sentinel in _repo_boundary_sentinels():
+        if (candidate_directory / each_sentinel).exists():
+            return True
+    return False
+
+
+def find_nearest_tests_directory(start_directory: Path) -> Path | None:
+    current_directory = start_directory
+    for _ in range(_parent_walk_limit()):
+        sibling_tests = current_directory / _tests_directory_name()
+        if sibling_tests.is_dir():
+            return sibling_tests
+        if _is_repo_boundary(current_directory):
+            return None
+        if current_directory.parent == current_directory:
+            return None
+        current_directory = current_directory.parent
+    return None
+
+
+def candidate_test_paths_for(production_path: Path) -> list[Path]:
+    directory = production_path.parent
+    stem = production_path.stem
+    extension = production_path.suffix.lower()
+    all_candidates: list[Path] = []
+
+    if extension == ".py":
+        all_candidates.append(directory / f"test_{stem}.py")
+        all_candidates.append(directory / f"{stem}_test.py")
+        nearest_tests_directory = find_nearest_tests_directory(directory)
+        if nearest_tests_directory is not None:
+            all_candidates.append(nearest_tests_directory / f"test_{stem}.py")
+        return all_candidates
+
+    if extension in {".tsx", ".ts", ".jsx", ".js"}:
+        all_candidates.append(directory / f"{stem}.test{extension}")
+        all_candidates.append(directory / f"{stem}.spec{extension}")
+        return all_candidates
+
+    return all_candidates
+
+
+def _test_file_encoding() -> str:
+    return "utf-8"
+
+
+def _safe_mtime(candidate_path: Path) -> float | None:
+    try:
+        return candidate_path.stat().st_mtime
+    except (FileNotFoundError, OSError):
+        return None
+
+
+def _read_candidate_text(candidate_path: Path) -> str | None:
+    try:
+        with candidate_path.open("r", encoding=_test_file_encoding(), errors="ignore") as each_file:
+            return each_file.read()
+    except (FileNotFoundError, OSError):
+        return None
+
+
+def _contains_test_evidence(candidate_path: Path) -> bool:
+    test_file_content = _read_candidate_text(candidate_path)
+    if test_file_content is None:
+        return False
+    for each_pattern in _test_function_patterns():
+        if each_pattern.search(test_file_content):
+            return True
+    return False
+
+
+def has_fresh_test(
+    all_candidates: list[Path],
+    freshness_seconds: int,
+) -> bool:
+    current_time = time.time()
+    for each_candidate in all_candidates:
+        candidate_mtime = _safe_mtime(each_candidate)
+        if candidate_mtime is None:
+            continue
+        age_seconds = current_time - candidate_mtime
+        if age_seconds > freshness_seconds:
+            continue
+        if not _contains_test_evidence(each_candidate):
+            continue
+        return True
+    return False
+
+
+def build_deny_reason(production_path: Path, all_candidates: list[Path]) -> str:
+    candidate_lines = "\n".join(f"  - {each_path}" for each_path in all_candidates)
+    return (
+        f"[TDD] Blocking write to production file: {production_path}\n"
+        f"No matching test file exists, or it has not been modified within the last "
+        f"{_freshness_seconds()} seconds.\n"
+        f"Expected one of:\n{candidate_lines}\n"
+        f"Write a failing test first (RED), then the minimum code to pass it (GREEN).\n"
+        f"Bypass (discouraged): include the sentinel '{_bypass_sentinel()}' in the file content."
+    )
+
+
+def emit_allow() -> None:
+    allow_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+        }
+    }
+    print(json.dumps(allow_payload))
+
+
+def emit_deny(reason: str) -> None:
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    }
+    print(json.dumps(deny_payload))
+
+
+def _matches_any_skip_pattern(name_lower: str, path_with_forward_slashes: str) -> bool:
+    path_components_lower = [each_part for each_part in path_with_forward_slashes.split("/") if each_part]
+    directory_components = path_components_lower[:-1]
+    skip_directory_components = _directory_skip_components()
+    for each_directory_component in directory_components:
+        if each_directory_component in skip_directory_components:
+            return True
+    for each_pattern in SKIP_PATTERNS:
+        if each_pattern.endswith("/"):
+            if each_pattern in path_with_forward_slashes:
+                return True
+            continue
+        if each_pattern in name_lower:
+            return True
+    return False
+
+
+def _extract_written_content(tool_name: str, tool_input: dict) -> str:
+    if tool_name == "Write":
+        return tool_input.get("content", "") or ""
+    if tool_name == "Edit":
+        return tool_input.get("new_string", "") or ""
+    if tool_name == "MultiEdit":
+        all_edits = tool_input.get("edits", []) or []
+        joined_new_strings: list[str] = []
+        for each_edit in all_edits:
+            if isinstance(each_edit, dict):
+                joined_new_strings.append(each_edit.get("new_string", "") or "")
+        return "\n".join(joined_new_strings)
+    return ""
+
+
 def main() -> None:
     try:
         input_data = json.load(sys.stdin)
     except json.JSONDecodeError:
         sys.exit(0)
 
+    tool_name = input_data.get("tool_name", "")
     tool_input = input_data.get("tool_input", {})
     file_path = tool_input.get("file_path", "")
 
@@ -42,19 +234,22 @@ def main() -> None:
 
     # Skip test files
     name_lower = path.name.lower()
-    path_str = str(path).lower()
-    if any(pattern in name_lower or pattern in path_str for pattern in SKIP_PATTERNS):
+    path_str = str(path).lower().replace("\\", "/")
+    if _matches_any_skip_pattern(name_lower, path_str):
         sys.exit(0)
 
     # Block production code - require confirmation
-    result = {
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "permissionDecision": "allow",
-            "additionalContext": "[BDD] Writing production code. Confirm you have a failing specification (test) first."
-        }
-    }
-    print(json.dumps(result))
+    written_content = _extract_written_content(tool_name, tool_input)
+    if _bypass_sentinel() in written_content:
+        emit_allow()
+        sys.exit(0)
+
+    all_candidates = candidate_test_paths_for(path)
+    if has_fresh_test(all_candidates, _freshness_seconds()):
+        emit_allow()
+        sys.exit(0)
+
+    emit_deny(build_deny_reason(path, all_candidates))
     sys.exit(0)