py-wlcli 0.8.0__py3-none-any.whl

wl_cli/commands/workflow.py

@@ -0,0 +1,477 @@
+"""GitHub Actions workflow validation using wrkflw."""
+
+import subprocess
+import sys
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import cast
+
+import click
+
+from .base import BaseCommand
+
+
+class ValidationMode(Enum):
+    """Validation behavior mode."""
+
+    WARN = "warn"  # Validation failures are warnings only
+    STRICT = "strict"  # Validation failures block progress
+
+
+@dataclass(frozen=True)
+class WorkflowValidationResult:
+    """Result of workflow validation."""
+
+    success: bool
+    validated_files: int
+    warnings: int
+    message: str
+    wrkflw_available: bool
+
+    def __str__(self) -> str:
+        """Format result for display."""
+        if not self.wrkflw_available:
+            return f"💡 {self.message}"
+        if not self.success:
+            return f"❌ Workflow validation FAILED: {self.message}"
+        if self.warnings > 0:
+            return (
+                f"⚠️  Workflow validation: {self.warnings} warning(s) - {self.message}"
+            )
+        return (
+            f"✅ Workflow validation passed - {self.validated_files} file(s) validated"
+        )
+
+
+class WorkflowChangeDetector:
+    """Detect changes to GitHub Actions workflow files."""
+
+    def __init__(self, repo_root: Path | None = None):
+        """Initialize detector.
+
+        Args:
+            repo_root: Path to repository root (default: cwd)
+        """
+        self.repo_root = repo_root or Path.cwd()
+
+    def _run_git_diff(self) -> list[str]:
+        """Run git diff to get changed files."""
+        try:
+            result = subprocess.run(
+                ["git", "diff", "--name-only", "HEAD"],
+                cwd=self.repo_root,
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            return [f.strip() for f in result.stdout.strip().split("\n") if f.strip()]
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return []
+
+    def _run_git_untracked(self) -> list[str]:
+        """Run git ls-files to get untracked files."""
+        try:
+            result = subprocess.run(
+                ["git", "ls-files", "--others", "--exclude-standard"],
+                cwd=self.repo_root,
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            return [f.strip() for f in result.stdout.strip().split("\n") if f.strip()]
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return []
+
+    def get_changed_workflows(self) -> list[str]:
+        """Get list of workflow files that have changed or are untracked."""
+        try:
+            changed = self._run_git_diff()
+            untracked = self._run_git_untracked()
+            all_files = set(changed + untracked)
+            return [f for f in all_files if ".github/workflows/" in f]
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return []
+
+    def has_workflow_changes(self) -> bool:
+        """Check if any workflow files have changed or are untracked."""
+        return len(self.get_changed_workflows()) > 0
+
+
+class WorkflowValidator:
+    """Validate GitHub Actions workflows using wrkflw."""
+
+    def __init__(
+        self,
+        repo_root: Path | None = None,
+        mode: ValidationMode = ValidationMode.WARN,
+    ):
+        """Initialize validator.
+
+        Args:
+            repo_root: Path to repository root (default: cwd)
+            mode: Validation mode (WARN or STRICT)
+        """
+        if repo_root:
+            self.repo_root = repo_root
+        else:
+            try:
+                self.repo_root = Path.cwd()
+            except FileNotFoundError:
+                self.repo_root = Path("/tmp")
+        self.mode = mode
+        self.detector = WorkflowChangeDetector(self.repo_root)
+
+    def _run_wrkflw(
+        self, files: list[str] | None = None
+    ) -> subprocess.CompletedProcess[str]:
+        """Run wrkflw validate command.
+
+        Args:
+            files: Optional list of files to validate (validates all if None)
+        """
+        cmd = ["wrkflw", "validate", "--exit-code"]
+        if files:
+            cmd.extend(files)
+
+        return subprocess.run(
+            cmd,
+            cwd=self.repo_root,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+    def validate_all(self) -> WorkflowValidationResult:
+        """Validate all workflow files.
+
+        Returns:
+            Validation result with success status and message
+        """
+        file_count = self._count_workflow_files()
+
+        try:
+            result = self._run_wrkflw()
+            output = result.stdout + result.stderr
+            return WorkflowValidationResult(
+                success=True,
+                validated_files=file_count,
+                warnings=0,
+                message=output or "All workflows valid",
+                wrkflw_available=True,
+            )
+        except FileNotFoundError:
+            return WorkflowValidationResult(
+                success=True,
+                validated_files=0,
+                warnings=0,
+                message="wrkflw not installed. Install with: brew install wrkflw",
+                wrkflw_available=False,
+            )
+        except subprocess.CalledProcessError as e:
+            error_output = (e.stdout + e.stderr).strip()
+            if self.mode == ValidationMode.STRICT:
+                return WorkflowValidationResult(
+                    success=False,
+                    validated_files=file_count,
+                    warnings=0,
+                    message=error_output or "Validation failed",
+                    wrkflw_available=True,
+                )
+            else:
+                # WARN mode - show warning but don't block
+                return WorkflowValidationResult(
+                    success=True,
+                    validated_files=file_count,
+                    warnings=1,
+                    message=error_output or "Validation warnings",
+                    wrkflw_available=True,
+                )
+
+    def validate_file(self, workflow_file: Path | str) -> WorkflowValidationResult:
+        """Validate a specific workflow file.
+
+        Args:
+            workflow_file: Path to workflow file to validate
+
+        Returns:
+            Validation result with success status and message
+        """
+        file_path = Path(workflow_file)
+        if not file_path.is_absolute():
+            file_path = self.repo_root / file_path
+
+        if not file_path.exists():
+            return WorkflowValidationResult(
+                success=True,
+                validated_files=0,
+                warnings=1,
+                message=f"Workflow file not found: {workflow_file}",
+                wrkflw_available=True,
+            )
+
+        try:
+            result = self._run_wrkflw([str(file_path)])
+            output = result.stdout + result.stderr
+            return WorkflowValidationResult(
+                success=True,
+                validated_files=1,
+                warnings=0,
+                message=output or "Workflow valid",
+                wrkflw_available=True,
+            )
+        except FileNotFoundError:
+            return WorkflowValidationResult(
+                success=True,
+                validated_files=0,
+                warnings=0,
+                message="wrkflw not installed. Install with: brew install wrkflw",
+                wrkflw_available=False,
+            )
+        except subprocess.CalledProcessError as e:
+            error_output = (e.stdout + e.stderr).strip()
+            if self.mode == ValidationMode.STRICT:
+                return WorkflowValidationResult(
+                    success=False,
+                    validated_files=0,
+                    warnings=0,
+                    message=error_output or "Validation failed",
+                    wrkflw_available=True,
+                )
+            else:
+                return WorkflowValidationResult(
+                    success=True,
+                    validated_files=0,
+                    warnings=1,
+                    message=error_output or "Validation warnings",
+                    wrkflw_available=True,
+                )
+
+    def validate_changed(self) -> WorkflowValidationResult:
+        """Validate only changed workflow files.
+
+        Returns:
+            Validation result with success status and message
+        """
+        changed_files = self.detector.get_changed_workflows()
+
+        if not changed_files:
+            return WorkflowValidationResult(
+                success=True,
+                validated_files=0,
+                warnings=0,
+                message="No workflow changes detected",
+                wrkflw_available=True,
+            )
+
+        try:
+            result = self._run_wrkflw(changed_files)
+            output = result.stdout + result.stderr
+            return WorkflowValidationResult(
+                success=True,
+                validated_files=len(changed_files),
+                warnings=0,
+                message=output or "All changed workflows valid",
+                wrkflw_available=True,
+            )
+        except FileNotFoundError:
+            return WorkflowValidationResult(
+                success=True,
+                validated_files=0,
+                warnings=0,
+                message="wrkflw not installed. Install with: brew install wrkflw",
+                wrkflw_available=False,
+            )
+        except subprocess.CalledProcessError as e:
+            error_output = (e.stdout + e.stderr).strip()
+            if self.mode == ValidationMode.STRICT:
+                return WorkflowValidationResult(
+                    success=False,
+                    validated_files=0,
+                    warnings=0,
+                    message=error_output or "Validation failed",
+                    wrkflw_available=True,
+                )
+            else:
+                return WorkflowValidationResult(
+                    success=True,
+                    validated_files=0,
+                    warnings=1,
+                    message=error_output or "Validation warnings",
+                    wrkflw_available=True,
+                )
+
+    def _count_workflow_files(self) -> int:
+        """Count workflow files in the repository."""
+        workflow_dir = self.repo_root / ".github" / "workflows"
+        if workflow_dir.exists():
+            return len(list(workflow_dir.glob("*.yml"))) + len(
+                list(workflow_dir.glob("*.yaml"))
+            )
+        return 0
+
+
+class WorkflowCoordinator:
+    """Coordinator for workflow validation operations."""
+
+    def __init__(
+        self,
+        repo_root: Path | None = None,
+        mode: ValidationMode = ValidationMode.WARN,
+        validator: WorkflowValidator | None = None,
+    ):
+        """Initialize coordinator."""
+        if validator is not None:
+            self.validator = validator
+        else:
+            self.validator = WorkflowValidator(repo_root=repo_root, mode=mode)
+
+    def execute(self, **kwargs) -> int:
+        """Execute workflow validation.
+
+        Args:
+            **kwargs: Command arguments
+
+        Returns:
+            Exit code (0 on success, 1 on failure in strict mode)
+        """
+        workflow_file = kwargs.get("workflow_file")
+        force_workflow = (
+            kwargs.get("workflow", False)
+            or kwargs.get("ci", False)
+            or kwargs.get("all", False)
+        )
+        strict_workflow = kwargs.get("strict_workflow", False)
+
+        if strict_workflow:
+            self.validator.mode = ValidationMode.STRICT
+
+        if workflow_file:
+            result = self.validator.validate_file(workflow_file)
+        elif force_workflow:
+            result = self.validator.validate_all()
+        elif self.validator.detector.has_workflow_changes():
+            result = self.validator.validate_changed()
+        else:
+            print("📋 No workflow changes detected, skipping validation")
+            return 0
+
+        print(str(result))
+
+        return 0 if result.success else 1
+
+
+class WorkflowCommand:
+    """Implementation of the workflow command."""
+
+    def __init__(self):
+        """Initialize workflow command."""
+        self.coordinator = WorkflowCoordinator()
+
+    @property
+    def name(self) -> str:
+        return "workflow"
+
+    @property
+    def help(self) -> str:
+        return "Validate GitHub Actions workflows using wrkflw"
+
+    def execute(
+        self,
+        workflow: bool,
+        ci: bool,
+        all: bool,
+        strict_workflow: bool,
+        workflow_file: str | None,
+    ) -> int:
+        """Execute workflow validation.
+
+        Args:
+            workflow: Force workflow validation
+            ci: Alias for --workflow
+            all: Alias for --workflow (validate all workflow files)
+            strict_workflow: Workflow validation failures block execution
+            workflow_file: Validate only the specified workflow file
+
+        Returns:
+            Exit code (0 on success, 1 on failure in strict mode)
+        """
+        return cast(
+            "int",
+            self.coordinator.execute(
+                workflow=workflow,
+                ci=ci,
+                all=all,
+                strict_workflow=strict_workflow,
+                workflow_file=workflow_file,
+            ),
+        )
+
+
+@click.command()
+@click.option(
+    "--workflow", is_flag=True, help="Force workflow validation regardless of changes"
+)
+@click.option("--ci", is_flag=True, help="Alias for --workflow")
+@click.option(
+    "--all",
+    "all_flag",
+    is_flag=True,
+    help="Alias for --workflow (validate all workflow files)",
+)
+@click.option(
+    "--strict-workflow",
+    is_flag=True,
+    help="Workflow validation failures block execution",
+)
+@click.option(
+    "--workflow-file", type=str, help="Validate only the specified workflow file"
+)
+@click.pass_context
+def workflow_command(
+    ctx: click.Context,
+    workflow: bool,
+    ci: bool,
+    all_flag: bool,
+    strict_workflow: bool,
+    workflow_file: str | None,
+) -> None:
+    """Validate GitHub Actions workflows using wrkflw."""
+    cmd = WorkflowCommand()
+    if ctx.obj and "coordinator" in ctx.obj:
+        cmd.coordinator = ctx.obj["coordinator"]
+    exit_code = cmd.execute(
+        workflow=workflow,
+        ci=ci,
+        all=all_flag,
+        strict_workflow=strict_workflow,
+        workflow_file=workflow_file,
+    )
+    if exit_code != 0:
+        sys.exit(exit_code)
+
+
+class WorkflowCommandWrapper(BaseCommand):
+    """GitHub Actions workflow validation command (legacy argparse interface)."""
+
+    def __init__(self):
+        """Initialize workflow command."""
+        self.coordinator = WorkflowCoordinator()
+
+    def run(self, *args, **kwargs):
+        """Run workflow validation command."""
+        return super().run(*args, **kwargs)
+
+    @property
+    def name(self) -> str:
+        return "workflow"
+
+    @property
+    def help(self) -> str:
+        return "Validate GitHub Actions workflows using wrkflw"
+
+    def execute(self, *args, **kwargs):
+        """Execute the workflow validation command."""
+        exit_code = self.coordinator.execute(*args, **kwargs)
+        if exit_code != 0:
+            sys.exit(exit_code)

wl_cli/env/__init__.py

@@ -0,0 +1,5 @@
+"""Environment domain (machine-readable five-state JSON via ``wl_cli.envelope``)."""
+
+from .cli import env_group
+
+__all__ = ["env_group"]

wl_cli/env/cli.py

@@ -0,0 +1,167 @@
+"""Click namespace for the ``env`` domain (issues #220, #221).
+
+``wl env check`` reports **the wl that is running** as a five-state JSON
+envelope (:mod:`wl_cli.envelope`); ``wl env repair`` installs the release
+floor with ``uv tool install``. The payload builder lives in
+:mod:`wl_cli.env_status` because the quality domain may not import this
+package (#220): the deprecated ``wl self capabilities`` alias in
+``wl_cli.commands`` calls the same builder, so the two commands cannot answer
+differently.
+
+This package may import the shared layer (:mod:`wl_cli.envelope`,
+:mod:`wl_cli.platform`, :mod:`wl_cli.capabilities`, :mod:`wl_cli.utils`) and
+nothing from ``wl_cli.cc`` / ``wl_cli.mcp`` / ``wl_cli.quality`` -- the
+dependency direction is enforced by ``tests/test_domain_import_direction.py``.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from typing import Any
+
+import click
+
+from ..env_status import (
+    INSTALL_ARGV,
+    INSTALL_COMMAND,
+    build_payload,
+    emit_check,
+    install_fields,
+)
+from ..envelope import OK_STATUSES, dump, exit_code
+
+#: Stable tool name in the repair envelope.
+REPAIR_TOOL = "env repair"
+
+#: How much of uv's output is quoted in a failure reason.
+_ERROR_EXCERPT_LIMIT = 400
+
+
+@click.group(
+    name="env",
+    help="Environment probes and repairs (machine-readable five-state JSON).",
+)
+def env_group() -> None:
+    """Environment domain entry point (``check`` and ``repair``)."""
+
+
+def _summary_lines(
+    status: str, reason: str | None, fields: dict[str, Any]
+) -> list[str]:
+    """Render the human-readable ``check`` summary (no ``--json``)."""
+    if status == "error":
+        return [f"wl env check: error: {reason}"]
+    native = "present" if fields["native_extension"] else "absent"
+    capabilities = ", ".join(fields["capabilities"])
+    lines = [
+        f"wl {fields['version']} ({status})",
+        f"executable: {fields['executable']}",
+        f"platform: {fields['platform']} (Python {fields['python']})",
+        f"native extension: {native}",
+        f"capabilities: {capabilities}",
+        f"install: {fields['install']['command']}",
+    ]
+    if reason:
+        lines.append(f"reason: {reason}")
+    return lines
+
+
+@env_group.command(name="check")
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    help="Emit one five-state JSON envelope on stdout.",
+)
+def check(as_json: bool) -> None:
+    """Report the running wl: version, executable, platform and capabilities.
+
+    Read-only. In ``--json`` mode stdout is exactly one envelope line and
+    diagnostics go to stderr; the probe itself runs in a temporary CWD and the
+    dispatcher skips the startup ``.wl`` self-sync (#220), so the caller's
+    directory is never written to.
+    """
+    if as_json:
+        raise SystemExit(emit_check())
+
+    status, reason, fields = build_payload()
+    for line in _summary_lines(status, reason, fields):
+        click.echo(line)
+    raise SystemExit(exit_code(status))
+
+
+def _excerpt(text: str) -> str:
+    """Flatten uv's output into one readable line (empty string when blank)."""
+    return " ".join(text.split())[:_ERROR_EXCERPT_LIMIT]
+
+
+def _run_install() -> tuple[str, str | None, dict[str, Any]]:
+    """Run the literal install command in a throwaway directory.
+
+    The command is executed as an argv list (``shell=False``) with an explicit
+    ``--python 3.12`` and no ``--force``: uv's own semantics make an identical
+    install a no-op, which is what makes ``wl env repair`` idempotent. The
+    temporary CWD keeps a stray ``uv.toml`` / ``.python-version`` in the
+    caller's directory from overriding the pinned interpreter.
+
+    Returns:
+        ``(status, reason, fields)`` -- ``repaired`` on rc 0 and
+        ``unverifiable`` otherwise (uv's exit code and an output excerpt are
+        quoted in ``reason``; a failure is never swallowed).
+    """
+    payload: dict[str, Any] = {
+        "command": INSTALL_COMMAND,
+        "floor": install_fields()["floor"],
+    }
+    with tempfile.TemporaryDirectory(prefix="wl-env-repair-") as workdir:
+        try:
+            result = subprocess.run(
+                list(INSTALL_ARGV),
+                cwd=workdir,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except FileNotFoundError as exc:
+            return "unverifiable", f"could not run uv: {exc}", payload
+        except OSError as exc:
+            return "unverifiable", f"could not run uv: {exc}", payload
+
+    payload["returncode"] = result.returncode
+    if result.returncode == 0:
+        return "repaired", None, payload
+
+    excerpt = _excerpt(result.stderr) or _excerpt(result.stdout)
+    reason = f"uv exited with code {result.returncode}"
+    if excerpt:
+        reason = f"{reason}: {excerpt}"
+    return "unverifiable", reason, payload
+
+
+@env_group.command(name="repair")
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    help="Emit one five-state JSON envelope on stdout.",
+)
+def repair(as_json: bool) -> None:
+    """Install the release floor with ``uv tool install`` (idempotent).
+
+    The exact command printed to stderr is the exact argv executed -- one
+    literal, no second copy. In ``--json`` mode stdout is one envelope line;
+    the command and any diagnostics stay on stderr.
+    """
+    click.echo(f"Running: {INSTALL_COMMAND}", err=True)
+    status, reason, fields = _run_install()
+
+    if as_json:
+        dump(status, status in OK_STATUSES, tool=REPAIR_TOOL, reason=reason, **fields)
+        raise SystemExit(exit_code(status))
+
+    if status == "repaired":
+        click.echo(f"repaired: {INSTALL_COMMAND}")
+    else:
+        click.echo(f"wl env repair: {status}: {reason}")
+    raise SystemExit(exit_code(status))