claude-dev-env 2.4.0 → 2.7.0

package/hooks/git-hooks/git_hooks_constants/__init__.py

@@ -9,7 +9,6 @@ import ...`` resolve against this file both inside the repo and under
 
 from __future__ import annotations
 
-
 STAGED_SCOPE_ARGUMENT: str = "--staged"
 BASE_REFERENCE_ARGUMENT: str = "--base"
 DEFAULT_REMOTE_BASE_REFERENCE: str = "origin/HEAD"
@@ -21,7 +20,7 @@ REMOTE_REFERENCE_FIELD_INDEX: int = 2
 GATE_PATH_OVERRIDE_ENV_VAR: str = "CODE_RULES_GATE_PATH"
 CLAUDE_HOME_ENV_VAR: str = "CLAUDE_HOME"
 CLAUDE_HOME_DEFAULT_SUBDIRECTORY: str = ".claude"
-GATE_SCRIPT_RELATIVE_PATH: tuple[str, ...] = (
+ALL_GATE_SCRIPT_RELATIVE_PATH: tuple[str, ...] = (
     "_shared",
     "pr-loop",
     "scripts",
@@ -65,3 +64,43 @@ PROTECTED_BRANCH_PUSH_BLOCK_MESSAGE: str = (
     "To push the feature branch to its own ref, name the destination: "
     "git push origin {local_branch}:refs/heads/{local_branch}"
 )
+GIT_EXECUTABLE_NAME: str = "git"
+GIT_COMMAND_SUCCESS_EXIT_CODE: int = 0
+GIT_OUTPUT_ENCODING_NAME: str = "utf-8"
+GIT_OUTPUT_DECODE_ERRORS_POLICY: str = "replace"
+GIT_COMMAND_UNAVAILABLE_MESSAGE: str = (
+    "claude-dev-env pre-push: could not run git ({error}), aborting"
+)
+GIT_REV_PARSE_SUBCOMMAND: str = "rev-parse"
+GIT_REV_PARSE_VERIFY_FLAG: str = "--verify"
+GIT_QUIET_FLAG: str = "--quiet"
+GIT_SYMBOLIC_REFERENCE_SUBCOMMAND: str = "symbolic-ref"
+GIT_COMMAND_TIMEOUT_SECONDS: int = 30
+GIT_FOR_EACH_REF_SUBCOMMAND: str = "for-each-ref"
+GIT_REFERENCE_SHORT_NAME_FORMAT_ARGUMENT: str = "--format=%(refname:short)"
+COMMIT_OBJECT_NAME_SUFFIX: str = "^{commit}"
+REMOTE_REFERENCE_NAME_PREFIX: str = "refs/remotes/"
+REMOTE_HEAD_SYMBOLIC_REFERENCE_TEMPLATE: str = "refs/remotes/{remote}/HEAD"
+REMOTE_HEAD_BRANCH_NAME: str = "HEAD"
+REMOTE_BRANCH_SHORT_NAME_TEMPLATE: str = "{remote}/{branch}"
+DEFAULT_REMOTE_NAME: str = "origin"
+REMOTE_NAME_ARGUMENT_INDEX: int = 1
+ALL_REJECTED_REMOTE_NAME_CHARACTERS: tuple[str, ...] = (
+    ":",
+    "/",
+    "*",
+    "?",
+    "[",
+    "\\",
+)
+ALL_FALLBACK_REMOTE_DEFAULT_BRANCH_NAMES: tuple[str, ...] = (
+    "main",
+    "master",
+    "trunk",
+    "develop",
+)
+UNRESOLVABLE_BASE_REFERENCE_MESSAGE: str = (
+    "claude-dev-env pre-push: no usable gate base -- {reference} names no commit and "
+    "the default branch of remote {remote!r} could not be read.\n"
+    "Set the remote head so the gate has a base: git remote set-head {remote} --auto"
+)

package/hooks/git-hooks/pre_push.py

@@ -18,14 +18,17 @@ installed; deletions and same-name pushes pass.
 Gate base: 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.
+falls back to the default branch of the remote git names in argv: its
+symbolic ref first, then the first candidate default branch that exists
+under that remote.
 
 Exit codes:
   0 - the push destination is allowed and its commits pass the gate (or
       the gate is not installed).
   1 - the push would land a non-protected local branch onto a protected
       remote branch, or a commit introduces a blocking violation.
-  2 - unexpected invocation failure (e.g., subprocess could not launch).
+  2 - unexpected invocation failure (e.g., subprocess could not launch), or
+      no gate base that git resolves.
 """
 
 from __future__ import annotations
@@ -36,6 +39,7 @@ import subprocess
 import sys
 from pathlib import Path
 
+from gate_utils import is_safe_regular_file, resolve_gate_script_path
 from git_hooks_constants import (
     ALL_PROTECTED_BRANCH_PUSH_NAMES,
     ALL_ZEROS_OBJECT_NAME_CHARACTER,
@@ -48,6 +52,11 @@ from git_hooks_constants import (
     CODE_REVIEW_STAMP_BLOCK_EXIT_CODE,
     DEFAULT_REMOTE_BASE_REFERENCE,
     GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE,
+    GIT_COMMAND_TIMEOUT_SECONDS,
+    GIT_COMMAND_UNAVAILABLE_MESSAGE,
+    GIT_EXECUTABLE_NAME,
+    GIT_OUTPUT_DECODE_ERRORS_POLICY,
+    GIT_OUTPUT_ENCODING_NAME,
     INVOKE_GATE_FAILURE_MESSAGE,
     LOCAL_BRANCH_REFERENCE_PREFIX,
     LOCAL_REFERENCE_FIELD_INDEX,
@@ -63,7 +72,60 @@ from git_hooks_constants import (
     STDIN_READ_FAILURE_MESSAGE,
     STDIN_REMOTE_OBJECT_FIELD_INDEX,
 )
-from gate_utils import is_safe_regular_file, resolve_gate_script_path
+from pre_push_base_reference import (
+    resolve_remote_name_from_arguments,
+    resolve_usable_base_reference,
+)
+
+
+def _report_unavailable_git(launch_error: Exception) -> int:
+    """Report a git that would not run, and hand back the exit code to use."""
+    git_command_unavailable_message = GIT_COMMAND_UNAVAILABLE_MESSAGE
+    sys.stderr.write(
+        git_command_unavailable_message.format(error=launch_error) + "\n"
+    )
+    return GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE
+
+
+class GitCommandUnavailable(RuntimeError):
+    """Git itself could not run: it failed to launch, or it timed out.
+
+    A git that runs and reports nothing is ordinary absence, which stays a
+    plain return. Separating the two keeps a broken toolchain from reading
+    as a repository that simply has no default branch.
+    """
+
+
+def run_git_text_command(all_command_arguments: list[str]) -> tuple[int, str]:
+    """Ask git a question and read back its answer.
+
+    Output decodes with a replacing policy, so a reference whose bytes are
+    invalid in this encoding becomes a marked string and matches nothing.
+
+    Args:
+        all_command_arguments: The git arguments following the executable name.
+
+    Returns:
+        The exit code paired with the trimmed standard output.
+
+    Raises:
+        GitCommandUnavailable: Git failed to launch or exceeded its timeout.
+    """
+    git_executable_name = GIT_EXECUTABLE_NAME
+    git_command_timeout_seconds = GIT_COMMAND_TIMEOUT_SECONDS
+    try:
+        completion = subprocess.run(
+            [git_executable_name, *all_command_arguments],
+            check=False,
+            capture_output=True,
+            timeout=git_command_timeout_seconds,
+        )
+    except (OSError, subprocess.SubprocessError) as launch_error:
+        raise GitCommandUnavailable(str(launch_error)) from launch_error
+    decoded_output = completion.stdout.decode(
+        GIT_OUTPUT_ENCODING_NAME, errors=GIT_OUTPUT_DECODE_ERRORS_POLICY
+    )
+    return completion.returncode, decoded_output.strip()
 
 
 def is_all_zeros_object_name(object_name: str) -> bool:
@@ -282,7 +344,16 @@ def main() -> int:
     if base_reference == no_parseable_stdin_lines_sentinel:
         print(no_parseable_stdin_lines_message, file=sys.stderr)
         return gate_infrastructure_failure_exit_code
-    code_rules_exit_code = invoke_gate(gate_script_path, base_reference)
+    remote_name = resolve_remote_name_from_arguments(sys.argv)
+    try:
+        usable_base_reference = resolve_usable_base_reference(
+            base_reference, remote_name, run_git_text_command
+        )
+    except GitCommandUnavailable as unavailable_error:
+        return _report_unavailable_git(unavailable_error)
+    if usable_base_reference is None:
+        return gate_infrastructure_failure_exit_code
+    code_rules_exit_code = invoke_gate(gate_script_path, usable_base_reference)
     if code_rules_exit_code != 0:
         return code_rules_exit_code
     return code_review_stamp_block_exit_code()

package/hooks/git-hooks/pre_push_base_reference.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Resolve the gate base that the pre-push hook hands to the CODE_RULES gate.
+
+Git names the pushed remote in the hook's first argument, so every reference
+built here keys on that name: the remote's symbolic head first, then the
+candidate default branches that exist under the same remote.
+
+The caller passes its own git seam, so a specification drives these functions
+with a table of references in place of a repository.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+
+from git_hooks_constants import (
+    ALL_FALLBACK_REMOTE_DEFAULT_BRANCH_NAMES,
+    ALL_REJECTED_REMOTE_NAME_CHARACTERS,
+    COMMIT_OBJECT_NAME_SUFFIX,
+    DEFAULT_REMOTE_BASE_REFERENCE,
+    DEFAULT_REMOTE_NAME,
+    GIT_COMMAND_SUCCESS_EXIT_CODE,
+    GIT_FOR_EACH_REF_SUBCOMMAND,
+    GIT_QUIET_FLAG,
+    GIT_REFERENCE_SHORT_NAME_FORMAT_ARGUMENT,
+    GIT_REV_PARSE_SUBCOMMAND,
+    GIT_REV_PARSE_VERIFY_FLAG,
+    GIT_SYMBOLIC_REFERENCE_SUBCOMMAND,
+    REMOTE_BRANCH_SHORT_NAME_TEMPLATE,
+    REMOTE_HEAD_BRANCH_NAME,
+    REMOTE_HEAD_SYMBOLIC_REFERENCE_TEMPLATE,
+    REMOTE_NAME_ARGUMENT_INDEX,
+    REMOTE_REFERENCE_NAME_PREFIX,
+    UNRESOLVABLE_BASE_REFERENCE_MESSAGE,
+)
+
+AskGit = Callable[[list[str]], tuple[int, str]]
+
+
+def resolve_remote_name_from_arguments(all_command_line_arguments: list[str]) -> str:
+    """Name the remote this push targets from the arguments git passed.
+
+    ::
+
+        ["pre-push", "upstream", "https://host/owner.git"] -> "upstream"
+        ["pre-push", "https://host/owner.git", ...]        -> "origin"
+
+    Git passes a remote name for a named remote and a URL for an ad-hoc push.
+    A URL carries a colon or a slash, which a remote name never does, so a URL
+    falls back to the default remote. A name carrying a glob character falls
+    back the same way, so no wildcard reaches the reference patterns built here.
+
+    Args:
+        all_command_line_arguments: The hook's own argument list.
+
+    Returns:
+        The remote name that every reference here is built from.
+    """
+    remote_name_argument_index = REMOTE_NAME_ARGUMENT_INDEX
+    if len(all_command_line_arguments) <= remote_name_argument_index:
+        return DEFAULT_REMOTE_NAME
+    pushed_argument = all_command_line_arguments[remote_name_argument_index].strip()
+    if not pushed_argument:
+        return DEFAULT_REMOTE_NAME
+    if any(
+        each_character in pushed_argument
+        for each_character in ALL_REJECTED_REMOTE_NAME_CHARACTERS
+    ):
+        return DEFAULT_REMOTE_NAME
+    return pushed_argument
+
+
+def _names_a_commit(reference_name: str, ask_git: AskGit) -> bool:
+    """Report whether git resolves a reference name to a commit."""
+    exit_code, _ = ask_git(
+        [
+            GIT_REV_PARSE_SUBCOMMAND,
+            GIT_REV_PARSE_VERIFY_FLAG,
+            GIT_QUIET_FLAG,
+            reference_name + COMMIT_OBJECT_NAME_SUFFIX,
+        ]
+    )
+    return exit_code == GIT_COMMAND_SUCCESS_EXIT_CODE
+
+
+def _first_existing_candidate_branch(remote_name: str, ask_git: AskGit) -> str | None:
+    """Name the first candidate default branch that exists under a remote.
+
+    Git lists matching references sorted by reference name, so the candidate
+    order below decides which listed name wins.
+    """
+    all_candidate_short_names = [
+        REMOTE_BRANCH_SHORT_NAME_TEMPLATE.format(remote=remote_name, branch=each_branch)
+        for each_branch in ALL_FALLBACK_REMOTE_DEFAULT_BRANCH_NAMES
+    ]
+    _, listed_short_names = ask_git(
+        [
+            GIT_FOR_EACH_REF_SUBCOMMAND,
+            GIT_REFERENCE_SHORT_NAME_FORMAT_ARGUMENT,
+            *(
+                REMOTE_REFERENCE_NAME_PREFIX + each_short_name
+                for each_short_name in all_candidate_short_names
+            ),
+        ]
+    )
+    all_existing_short_names = set(listed_short_names.split())
+    for each_candidate_short_name in all_candidate_short_names:
+        if each_candidate_short_name in all_existing_short_names:
+            return each_candidate_short_name
+    return None
+
+
+def _remote_default_branch_reference(remote_name: str, ask_git: AskGit) -> str | None:
+    """Name a remote's default branch from its symbolic ref, then candidates."""
+    exit_code, symbolic_target = ask_git(
+        [
+            GIT_SYMBOLIC_REFERENCE_SUBCOMMAND,
+            GIT_QUIET_FLAG,
+            REMOTE_HEAD_SYMBOLIC_REFERENCE_TEMPLATE.format(remote=remote_name),
+        ]
+    )
+    if exit_code == GIT_COMMAND_SUCCESS_EXIT_CODE and symbolic_target:
+        return symbolic_target.removeprefix(REMOTE_REFERENCE_NAME_PREFIX)
+    return _first_existing_candidate_branch(remote_name, ask_git)
+
+
+def _report_unresolvable_base(base_reference: str, remote_name: str) -> None:
+    """Tell the pusher which remote head to set so the gate gains a base."""
+    sys.stderr.write(
+        UNRESOLVABLE_BASE_REFERENCE_MESSAGE.format(reference=base_reference, remote=remote_name)
+        + "\n"
+    )
+
+
+def resolve_usable_base_reference(
+    base_reference: str, remote_name: str, ask_git: AskGit
+) -> str | None:
+    """Turn the gate base into a name git can actually resolve.
+
+    ::
+
+        "origin/HEAD" on a clone that has it   -> "origin/HEAD"
+        pushed to "upstream" on such a clone   -> "upstream/HEAD"
+        "origin/HEAD" on a clone that lacks it -> "origin/main"
+        a commit name git does not know        -> None
+
+    Args:
+        base_reference: The gate base drawn from the push's stdin lines.
+        remote_name: The remote git named in the hook's arguments.
+        ask_git: The seam that runs a git command and reads its output.
+
+    Returns:
+        A reference git resolves, or None when no such reference is found.
+    """
+    if base_reference != DEFAULT_REMOTE_BASE_REFERENCE:
+        return base_reference
+    remote_head_reference = REMOTE_BRANCH_SHORT_NAME_TEMPLATE.format(
+        remote=remote_name, branch=REMOTE_HEAD_BRANCH_NAME
+    )
+    if _names_a_commit(remote_head_reference, ask_git):
+        return remote_head_reference
+    default_branch_reference = _remote_default_branch_reference(remote_name, ask_git)
+    if default_branch_reference is None:
+        _report_unresolvable_base(remote_head_reference, remote_name)
+    return default_branch_reference

package/hooks/git-hooks/test_config.py

@@ -1,20 +1,5 @@
 from __future__ import annotations
 
-import importlib
-import sys
-from pathlib import Path
-
-
-SCRIPT_DIRECTORY = Path(__file__).resolve().parent
-_git_hooks_directory_string = str(SCRIPT_DIRECTORY)
-while _git_hooks_directory_string in sys.path:
-    sys.path.remove(_git_hooks_directory_string)
-sys.path.insert(0, _git_hooks_directory_string)
-for each_module_name in list(sys.modules):
-    if each_module_name == "config" or each_module_name.startswith("config."):
-        del sys.modules[each_module_name]
-importlib.invalidate_caches()
-
 import git_hooks_constants
 
 

package/hooks/git-hooks/test_gate_utils.py

@@ -1,23 +1,11 @@
+"""Specifications for the gate-script path resolution and its trust check."""
+
 from __future__ import annotations
 
-import importlib
-import sys
 from pathlib import Path
 
-import pytest
-
-
-SCRIPT_DIRECTORY = Path(__file__).resolve().parent
-_git_hooks_directory_string = str(SCRIPT_DIRECTORY)
-while _git_hooks_directory_string in sys.path:
-    sys.path.remove(_git_hooks_directory_string)
-sys.path.insert(0, _git_hooks_directory_string)
-for each_module_name in list(sys.modules):
-    if each_module_name == "config" or each_module_name.startswith("config."):
-        del sys.modules[each_module_name]
-importlib.invalidate_caches()
-
 import gate_utils
+import pytest
 
 
 def test_resolve_gate_script_path_uses_override_env_var_when_set(

package/hooks/git-hooks/test_pre_commit.py

@@ -1,23 +1,9 @@
 from __future__ import annotations
 
-import importlib
-import sys
 from pathlib import Path
 
-import pytest
-
-
-SCRIPT_DIRECTORY = Path(__file__).resolve().parent
-_git_hooks_directory_string = str(SCRIPT_DIRECTORY)
-while _git_hooks_directory_string in sys.path:
-    sys.path.remove(_git_hooks_directory_string)
-sys.path.insert(0, _git_hooks_directory_string)
-for each_module_name in list(sys.modules):
-    if each_module_name == "config" or each_module_name.startswith("config."):
-        del sys.modules[each_module_name]
-importlib.invalidate_caches()
-
 import pre_commit
+import pytest
 
 
 def make_gate_script_returning(exit_code: int, target_path: Path) -> Path: