py-wlcli 0.8.0__py3-none-any.whl

wl_cli/commands/git/git_flow.py

@@ -0,0 +1,86 @@
+"""Git Flow CLI commands."""
+
+from __future__ import annotations
+
+import click
+
+from .config import GitFlowConfig
+from .git_facts import get_changed_files, get_current_branch
+from .hook import format_agent_hint
+from .policy import GitFlowPolicyValidator, PushContext
+
+
+def run_git_flow_check_text() -> str:
+    """Run the Git Flow check core and return the exact banner text.
+
+    Returns the multi-line banner text that ``wl git-flow check`` prints: the
+    ``Git-Flow-Agent-Hint:`` block followed by the status lines. This is the
+    pure-hint entry point used by the pre-commit hook: it never raises, so the
+    caller can display the banner without gating on the result.
+    """
+    text, _ok = _run_git_flow_check()
+    return text
+
+
+@click.group(name="git-flow")
+def git_flow_command() -> None:
+    """Check Git Flow branch policy."""
+
+
+@git_flow_command.command(name="check")
+def check_command() -> None:
+    """Check the current branch against Git Flow policy."""
+    text, ok = _run_git_flow_check()
+    click.echo(text)
+    if not ok:
+        raise click.ClickException("Git Flow policy check failed")
+
+
+def _run_git_flow_check() -> tuple[str, bool]:
+    """Shared core: run the policy and return (banner_text, ok)."""
+    config = GitFlowConfig()
+    validator = GitFlowPolicyValidator(config)
+    branch = get_current_branch()
+    branch_type = validator.classify_branch(branch)
+    source = _source_for_branch_type(config, branch_type)
+    changed_files = (
+        get_changed_files(source, file_filters=["VERSION", "CHANGELOG.md"])
+        if source
+        else frozenset()
+    )
+    result = validator.validate_push(
+        PushContext(local_branch=branch, changed_files=changed_files)
+    )
+
+    lines = [
+        format_agent_hint(result),
+        f"Git Flow check: {result.status}",
+        f"Branch: {result.branch}",
+        f"Type: {branch_type}",
+    ]
+    if source:
+        lines.append(f"Source: {source}")
+    targets = _targets_for_branch_type(config, branch_type)
+    if targets:
+        lines.append(f"Target: {', '.join(targets)}")
+    lines.extend(
+        [
+            f"Rule: {result.rule}",
+            f"Fix: {result.fix}",
+            f"Config: {result.config_source}",
+        ]
+    )
+
+    return "\n".join(lines), result.ok
+
+
+def _source_for_branch_type(config: GitFlowConfig, branch_type: str) -> str | None:
+    if branch_type in {"feature", "release", "hotfix"}:
+        return config.source_branch(branch_type)
+    return None
+
+
+def _targets_for_branch_type(config: GitFlowConfig, branch_type: str) -> list[str]:
+    if branch_type in {"feature", "release", "hotfix"}:
+        return config.merge_targets(branch_type)
+    return []

wl_cli/commands/git/hook.py

@@ -0,0 +1,112 @@
+"""Pre-push hook helpers for Git Flow policy validation."""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import TYPE_CHECKING
+
+from .policy import PolicyResult, PushContext
+
+if TYPE_CHECKING:
+    from .push_update import PushUpdate
+
+BRANCH_NAME_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/-]*$")
+
+
+def build_push_context(
+    local_branch: str,
+    updates: tuple[PushUpdate, ...],
+    changed_files: frozenset[str],
+) -> PushContext:
+    """Build the policy context from pre-push updates parsed once by the caller."""
+    return PushContext(
+        local_branch=local_branch,
+        remote_branch=_remote_branch_from_updates(updates),
+        changed_files=changed_files,
+        bypass_token=os.environ.get("WL_GIT_FLOW_BYPASS"),
+    )
+
+
+def format_agent_hint(result: PolicyResult) -> str:
+    hint = result.agent_hint
+    lines = ["Git-Flow-Agent-Hint:"]
+    for key in (
+        "branch",
+        "branch_type",
+        "status",
+        "recommended_action",
+        "source_branch",
+        "merge_targets",
+        "allowed_push",
+        "direct_push_allowed",
+        "protected_target_push_allowed",
+        "required_changes",
+        "missing_changes",
+        "rename_required",
+        "suggested_branch_patterns",
+        "next_step",
+        "agent_policy",
+    ):
+        lines.extend(_format_yaml_field(key, getattr(hint, key)))
+    return "\n".join(lines)
+
+
+def format_hook_failure(result: PolicyResult) -> str:
+    return "\n".join(
+        [
+            f"Git Flow check: {result.status}",
+            f"Branch: {result.branch}",
+            f"Rule: {result.rule}",
+            f"Fix: {result.fix}",
+            f"Config: {result.config_source}",
+            "Run `wl git-flow check` for details.",
+        ]
+    )
+
+
+def _format_yaml_field(key: str, value: object) -> list[str]:
+    if isinstance(value, bool):
+        return [f"  {key}: {str(value).lower()}"]
+    if isinstance(value, str):
+        return [f"  {key}: {_quote_yaml_string(value)}"]
+    if isinstance(value, tuple):
+        if not value:
+            return [f"  {key}: []"]
+        return [f"  {key}:"] + [f"    - {_quote_yaml_string(item)}" for item in value]
+    raise TypeError(f"unsupported agent hint value for {key}: {type(value).__name__}")
+
+
+def _quote_yaml_string(value: str) -> str:
+    escaped = (
+        value.replace("\\", "\\\\")
+        .replace('"', '\\"')
+        .replace("\n", "\\n")
+        .replace("\r", "\\r")
+        .replace("\t", "\\t")
+    )
+    return '"' + escaped + '"'
+
+
+def _remote_branch_from_updates(updates: tuple[PushUpdate, ...]) -> str | None:
+    """First safe branch target among the updates, else ``None``.
+
+    An unsafe name does not end the scan: a push may carry several heads, and
+    skipping the bad line keeps the check on the remaining ones (#163, keeping
+    the pre-split behaviour).
+    """
+    for update in updates:
+        branch_name = update.branch_name
+        if branch_name is None:
+            continue
+        if _is_safe_branch_name(branch_name):
+            return branch_name
+    return None
+
+
+def _is_safe_branch_name(branch_name: str) -> bool:
+    return (
+        bool(BRANCH_NAME_PATTERN.fullmatch(branch_name))
+        and ".." not in branch_name
+        and not branch_name.endswith("/")
+    )

wl_cli/commands/git/policy.py

@@ -0,0 +1,216 @@
+"""Pure Git Flow policy validation."""
+
+from __future__ import annotations
+
+import hmac
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from .config import GitFlowConfig
+
+PolicyStatus = Literal["OK", "WARN", "BLOCKED"]
+
+
+@dataclass(frozen=True)
+class PushContext:
+    local_branch: str
+    remote_branch: str | None = None
+    changed_files: frozenset[str] = field(default_factory=frozenset)
+    bypass_token: str | None = None
+
+
+@dataclass(frozen=True)
+class AgentHint:
+    branch: str
+    branch_type: str
+    status: PolicyStatus
+    recommended_action: str
+    source_branch: str
+    merge_targets: tuple[str, ...]
+    allowed_push: bool
+    direct_push_allowed: bool
+    protected_target_push_allowed: bool
+    required_changes: tuple[str, ...]
+    missing_changes: tuple[str, ...]
+    rename_required: bool
+    suggested_branch_patterns: tuple[str, ...]
+    next_step: str
+    agent_policy: str
+
+
+@dataclass(frozen=True)
+class PolicyResult:
+    ok: bool
+    status: PolicyStatus
+    branch: str
+    rule: str
+    fix: str
+    config_source: str
+    agent_hint: AgentHint
+
+
+class GitFlowPolicyValidator:
+    BYPASS_TOKEN = "release-automation"
+
+    def __init__(self, config: GitFlowConfig) -> None:
+        self.config = config
+
+    def classify_branch(self, branch_name: str) -> str:
+        if branch_name == self.config.main_branch:
+            return "main"
+        if branch_name == self.config.develop_branch:
+            return "develop"
+        for branch_type in ("feature", "release", "hotfix"):
+            if branch_name.startswith(self.config.branch_prefix(branch_type)):
+                return branch_type
+        return "unknown"
+
+    def validate_push(self, context: PushContext) -> PolicyResult:
+        if not context.local_branch:
+            return self._blocked(
+                "unknown",
+                "could not determine the current branch for Git Flow validation.",
+                "run `git branch --show-current`, then rerun wl git-flow check.",
+            )
+
+        target_branch = context.remote_branch or context.local_branch
+        target_type = self.classify_branch(target_branch)
+
+        if target_type in {"main", "develop"} and not self._has_bypass(context):
+            return self._blocked(
+                target_branch,
+                f"direct human pushes to protected branch {target_branch} are not allowed.",
+                f"push a feature/*, release/*, or hotfix/* branch and open a PR into {target_branch}.",
+            )
+
+        local_type = self.classify_branch(context.local_branch)
+        if context.local_branch == "features":
+            return PolicyResult(
+                ok=True,
+                status="WARN",
+                branch="features",
+                rule="features is a legacy working branch; canonical feature branches use feature/*.",
+                fix="continue for now, but prefer feature/<name> for new work.",
+                config_source=self.config.config_source,
+                agent_hint=self._agent_hint("features", "legacy_features", "WARN"),
+            )
+
+        if local_type in {"release", "hotfix"}:
+            evidence_result = self._validate_release_evidence(context, local_type)
+            if evidence_result is not None:
+                return evidence_result
+
+        return PolicyResult(
+            ok=True,
+            status="OK",
+            branch=context.local_branch,
+            rule="branch satisfies Git Flow policy.",
+            fix="push this branch and open the configured PR when ready.",
+            config_source=self.config.config_source,
+            agent_hint=self._agent_hint(context.local_branch, local_type, "OK"),
+        )
+
+    def _validate_release_evidence(
+        self, context: PushContext, branch_type: str
+    ) -> PolicyResult | None:
+        required_files = frozenset({"VERSION", "CHANGELOG.md"})
+        missing_files = required_files - context.changed_files
+        if not missing_files:
+            return None
+
+        source_branch = self.config.source_branch(branch_type)
+        missing_list = " and ".join(sorted(missing_files))
+        return self._blocked(
+            context.local_branch,
+            f"{branch_type} branches must change VERSION and CHANGELOG.md compared with {source_branch}; missing {missing_list}.",
+            "update VERSION and CHANGELOG.md, then rerun wl git-flow check.",
+            self._agent_hint(
+                context.local_branch,
+                branch_type,
+                "BLOCKED",
+                missing_changes=tuple(sorted(missing_files)),
+            ),
+        )
+
+    def _has_bypass(self, context: PushContext) -> bool:
+        if context.bypass_token is None:
+            return False
+        return hmac.compare_digest(context.bypass_token, self.BYPASS_TOKEN)
+
+    def _blocked(
+        self, branch: str, rule: str, fix: str, agent_hint: AgentHint | None = None
+    ) -> PolicyResult:
+        branch_type = self.classify_branch(branch) if branch != "unknown" else "unknown"
+        return PolicyResult(
+            ok=False,
+            status="BLOCKED",
+            branch=branch,
+            rule=rule,
+            fix=fix,
+            config_source=self.config.config_source,
+            agent_hint=agent_hint
+            or self._agent_hint(branch, branch_type, "BLOCKED", allowed_push=False),
+        )
+
+    def _agent_hint(
+        self,
+        branch: str,
+        branch_type: str,
+        status: PolicyStatus,
+        missing_changes: tuple[str, ...] = (),
+        allowed_push: bool = True,
+    ) -> AgentHint:
+        required_changes: tuple[str, ...] = ()
+        source_branch = ""
+        merge_targets: tuple[str, ...] = ()
+        recommended_action = "rename_or_create_git_flow_branch"
+        rename_required = False
+        suggested_branch_patterns: tuple[str, ...] = ()
+        next_step = "Create a branch that matches feature/<name>, release/<version>, or hotfix/<name> depending on the work intent."
+
+        if branch_type == "feature":
+            source_branch = self.config.source_branch("feature")
+            merge_targets = tuple(self.config.merge_targets("feature"))
+            recommended_action = "create_pull_request"
+            next_step = "Push the current feature branch and open a PR into develop."
+        elif branch_type == "legacy_features":
+            source_branch = self.config.develop_branch
+            merge_targets = (self.config.develop_branch,)
+            recommended_action = "rename_branch_by_change_intent"
+            rename_required = True
+            suggested_branch_patterns = (
+                "feature/<short-topic>",
+                "release/<version>",
+                "hotfix/<short-topic>",
+            )
+            next_step = "Inspect the current code changes, infer the work intent, suggest a standard Git Flow branch name, and ask the user before renaming or pushing."
+        elif branch_type in {"release", "hotfix"}:
+            source_branch = self.config.source_branch(branch_type)
+            merge_targets = tuple(self.config.merge_targets(branch_type))
+            required_changes = ("VERSION", "CHANGELOG.md")
+            recommended_action = (
+                f"verify_{branch_type}_evidence_then_create_pull_requests"
+            )
+            next_step = "Confirm VERSION and CHANGELOG.md, then open PRs to main and back to develop."
+        elif branch_type in {"main", "develop"}:
+            recommended_action = "create_topic_branch"
+            next_step = "Do not direct-push; create a feature/*, release/*, or hotfix/* branch and open a PR."
+
+        return AgentHint(
+            branch=branch,
+            branch_type=branch_type,
+            status=status,
+            recommended_action=recommended_action,
+            source_branch=source_branch,
+            merge_targets=merge_targets,
+            allowed_push=allowed_push,
+            direct_push_allowed=allowed_push,
+            protected_target_push_allowed=branch_type not in {"main", "develop"},
+            required_changes=required_changes,
+            missing_changes=missing_changes,
+            rename_required=rename_required,
+            suggested_branch_patterns=suggested_branch_patterns,
+            next_step=next_step,
+            agent_policy="Suggest only; ask the user before executing git branch -m, git checkout -b, git push, gh pr create, merge, or branch deletion.",
+        )

wl_cli/commands/git/push_update.py

@@ -0,0 +1,82 @@
+"""Single parse of git pre-push stdin (#163).
+
+Git hands a pre-push hook one line per ref being pushed:
+
+    <local-ref> <local-sha1> <remote-ref> <remote-sha1>
+
+Three call sites used to split that text on their own: the vendored hook's
+``parse_remote_refs`` (remote refs only), its ``_has_live_head_update`` (local
+sha only) and ``git/hook.py``'s remote-branch lookup (``parts[2]`` only). The
+shape of "what counts as a push" therefore had to be changed in three places
+at once. This module parses it once, keeping both sides of each ref, so the
+hook and its Python helpers read fields instead of re-splitting stdin.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+HEADS_PREFIX = "refs/heads/"
+
+
+@dataclass(frozen=True)
+class PushUpdate:
+    """One ``<local-ref> <local-sha> <remote-ref> <remote-sha>`` pre-push line."""
+
+    local_ref: str
+    local_sha: str
+    remote_ref: str
+    remote_sha: str
+
+    @property
+    def is_branch(self) -> bool:
+        """Whether this update targets a branch (tags and other refs excluded)."""
+        return self.remote_ref.startswith(HEADS_PREFIX)
+
+    @property
+    def is_delete(self) -> bool:
+        """Whether this update only deletes the remote ref.
+
+        Deletions carry ``(delete)`` or an all-zero local sha and no content
+        for the Git Flow evidence rules to judge.
+        """
+        return self.local_sha == "(delete)" or (
+            self.local_sha != "" and self.local_sha.strip("0") == ""
+        )
+
+    @property
+    def branch_name(self) -> str | None:
+        """The remote branch name, or ``None`` for non-branch refs.
+
+        A deletion line still yields its branch name: branch protection needs
+        to know which branch would be deleted.
+        """
+        if not self.is_branch:
+            return None
+        return self.remote_ref.removeprefix(HEADS_PREFIX)
+
+
+def parse_push_updates(stdin_text: str) -> tuple[PushUpdate, ...]:
+    """Parse pre-push stdin into updates, one ``splitlines``/``split`` pass.
+
+    Blank lines and lines with fewer than four fields are skipped: git never
+    emits them, but a truncated or hand-fed stream must not raise in a hook
+    that is supposed to fail open.
+    """
+    updates: list[PushUpdate] = []
+    for line in stdin_text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        parts = line.split()
+        if len(parts) < 4:
+            continue
+        updates.append(
+            PushUpdate(
+                local_ref=parts[0],
+                local_sha=parts[1],
+                remote_ref=parts[2],
+                remote_sha=parts[3],
+            )
+        )
+    return tuple(updates)

wl_cli/commands/initenv/__init__.py

@@ -0,0 +1 @@
+# Init command is registered via Click group in initenv.py

wl_cli/commands/initenv/common/__init__.py

@@ -0,0 +1,23 @@
+"""Common infrastructure for initenv module."""
+
+from .error_handler import error_handler
+from .exceptions import (
+    CargoSyncError,
+    GitInitError,
+    GitLfsInitError,
+    InitEnvError,
+    ProjectStructureError,
+    VenvCreationError,
+)
+
+__all__ = [
+    # Exceptions
+    "InitEnvError",
+    "ProjectStructureError",
+    "VenvCreationError",
+    "GitInitError",
+    "GitLfsInitError",
+    "CargoSyncError",
+    # Decorators
+    "error_handler",
+]

wl_cli/commands/initenv/common/check_git_bash.py

@@ -0,0 +1,78 @@
+"""Shared Git Bash detection utility for initenv components."""
+
+import os
+from pathlib import Path
+
+from ....utils.logging import log_debug, log_info
+from ....utils.platform_adapter import PlatformAdapter
+
+_check_cache: bool | None = None
+
+
+def _find_git_bash() -> str | None:
+    """Find Git Bash executable path."""
+    common_paths = [
+        r"C:\Program Files\Git\bin\bash.exe",
+        r"C:\Program Files (x86)\Git\bin\bash.exe",
+        r"C:\Git\bin\bash.exe",
+    ]
+    for path in common_paths:
+        if Path(path).exists():
+            return path
+
+    # Try to find git bash using where command
+    try:
+        import subprocess
+
+        result = subprocess.run(
+            ["where", "bash"], capture_output=True, text=True, check=False
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip().split("\n")[0]
+    except Exception:
+        pass
+
+    return None
+
+
+def _handle_git_bash_result(git_bash_path: str | None) -> None:
+    """Handle Git Bash path resolution."""
+    if git_bash_path:
+        bash_dir = str(Path(git_bash_path).parent)
+        os.environ.setdefault("GIT_BASH_PATH", git_bash_path)
+        os.environ.setdefault("GIT_BASH_DIR", bash_dir)
+        # Add Git Bash directory to PATH so hooks can find it during execution
+        path_env = os.environ.get("PATH", "")
+        if bash_dir not in path_env:
+            os.environ["PATH"] = f"{bash_dir}{os.pathsep}{path_env}"
+        log_debug(f"Git Bash found at: {git_bash_path}")
+    else:
+        log_info(
+            "Warning: Git Bash not found. Git hooks may not work properly on Windows."
+        )
+        log_info("警告: 未找到 Git Bash，Git 钩子在 Windows 上可能无法正常工作。")
+
+
+def check_git_bash_installed() -> None:
+    """Check if Git Bash is installed on Windows. Results cached after first call.
+
+    Git Bash is required for Git hooks to work properly on Windows.
+    If Git Bash is not found, display a warning message.
+    If Git Bash is found but not in PATH, add its directory to the project environment.
+    """
+    global _check_cache
+    if _check_cache is not None:
+        return
+
+    if not PlatformAdapter.is_windows():
+        _check_cache = True
+        return
+
+    try:
+        git_bash_path = _find_git_bash()
+        _handle_git_bash_result(git_bash_path)
+    except Exception as e:
+        log_info(f"Warning: Error checking for Git Bash: {e}")
+        log_info(f"警告: 检查Git Bash时出错: {e}")
+    finally:
+        _check_cache = True

wl_cli/commands/initenv/common/error_handler.py

@@ -0,0 +1,68 @@
+"""Error handling utilities for initialization commands."""
+
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar, cast
+
+from wl_cli.exceptions import CommandError
+from wl_cli.utils.logging import log_error_pair
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def error_handler(
+    message: str | F | None = None,
+) -> Callable[..., Any] | F:
+    """
+    Decorator to handle exceptions in initialization functions.
+
+    Args:
+        message: Custom error message to use if provided,
+                 or the function itself when used without parentheses
+
+    Returns:
+        Callable: Decorated function
+    """
+    # Case 1: decorator used without parentheses: @error_handler
+    if message is not None and callable(message):
+        func: F = message
+
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:
+                # Generate error message
+                error_msg = str(e)
+
+                # Log the error
+                log_error_pair(f"Error: {error_msg}", f"错误: {error_msg}")
+
+                # Raise CommandError with the error message
+                raise CommandError(error_msg) from e
+
+        return cast("F", wrapper)
+
+    # Case 2: decorator used with parentheses: @error_handler("custom message")
+    message_str: str | None = message
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:
+                # Generate error message
+                error_msg = str(e)
+                if message_str:
+                    error_msg = f"{message_str}: {error_msg}"
+
+                # Log the error
+                log_error_pair(f"Error: {error_msg}", f"错误: {error_msg}")
+
+                # Raise CommandError with the error message
+                raise CommandError(error_msg) from e
+
+        return cast("F", wrapper)
+
+    return decorator