code-mower 0.5.0b5__py3-none-any.whl

code_mower/doctor_checks/output.py

@@ -0,0 +1,86 @@
+"""Human-readable doctor output rendering."""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from collections.abc import Iterable
+
+from .groups import GROUP_LABELS, doctor_check_group_id
+from .models import STATUS_FAIL, STATUS_SKIP, STATUS_WARN, DoctorCheck
+from .models import DoctorReport
+
+
+def doctor_output_group(check: DoctorCheck) -> str:
+    """Return the human-output group for a doctor check."""
+
+    return doctor_check_group_id(check.name, check.lane)
+
+
+def _group_checks(checks: Iterable[DoctorCheck]) -> OrderedDict[str, list[DoctorCheck]]:
+    grouped: OrderedDict[str, list[DoctorCheck]] = OrderedDict(
+        (group_id, []) for group_id in GROUP_LABELS
+    )
+    for check in checks:
+        grouped.setdefault(doctor_output_group(check), []).append(check)
+    return grouped
+
+
+def _format_status_summary(report: DoctorReport) -> str:
+    parts = [f"{len(report.checks)} total"]
+    if report.failures:
+        parts.append(f"{report.failures} failed")
+    if report.warnings:
+        parts.append(f"{report.warnings} warnings")
+    skipped = sum(1 for check in report.checks if check.status == STATUS_SKIP)
+    if skipped:
+        parts.append(f"{skipped} skipped")
+    if len(parts) == 1:
+        parts.append("all passing")
+    return ", ".join(parts)
+
+
+def _format_check(check: DoctorCheck) -> list[str]:
+    lane = f" [{check.lane}]" if check.lane else ""
+    lines = [f"- {check.status.upper()} {check.name}{lane}: {check.message}"]
+    if check.remediation:
+        lines.append(f"  remediation: {check.remediation}")
+    return lines
+
+
+def render_doctor_text(report: DoctorReport) -> str:
+    """Render a doctor report for terminal output."""
+    lines = [
+        "Code Mower doctor",
+        f"Status: {report.status}",
+        f"Config: {report.config_path}",
+        f"Provider templates: {report.provider_templates_path}",
+    ]
+    if report.profile:
+        lines.append(f"Profile: {report.profile}")
+    lines.append(f"Checks: {_format_status_summary(report)}")
+    lines.append("")
+
+    if not report.checks:
+        lines.append("No checks ran.")
+        return "\n".join(lines) + "\n"
+
+    for group_id, checks in _group_checks(report.checks).items():
+        if not checks:
+            continue
+        failed = sum(1 for check in checks if check.status == STATUS_FAIL)
+        warnings = sum(1 for check in checks if check.status == STATUS_WARN)
+        summary = []
+        if failed:
+            summary.append(f"{failed} failed")
+        if warnings:
+            summary.append(f"{warnings} warnings")
+        heading = GROUP_LABELS.get(group_id, group_id.title())
+        if summary:
+            heading = f"{heading} ({', '.join(summary)})"
+        lines.append(heading)
+        for check in checks:
+            lines.extend(_format_check(check))
+        lines.append("")
+    if lines[-1] == "":
+        lines.pop()
+    return "\n".join(lines) + "\n"

code_mower/doctor_checks/presets.py

@@ -0,0 +1,64 @@
+"""First-run doctor presets and package-aware path resolution."""
+
+from __future__ import annotations
+
+from argparse import Namespace
+from pathlib import Path
+
+from code_mower import package as code_mower_package
+
+
+def resolve_doctor_config_path_for_script(
+    config_arg: str,
+    *,
+    easy: bool = False,
+    script_path: Path,
+) -> Path:
+    path = Path(config_arg)
+    if path.is_file() or config_arg != "code-mower.yml" or not easy:
+        return path
+
+    script_path = script_path.resolve()
+    candidates = [
+        script_path.parent / "templates" / "code-mower.example.yml",
+        script_path.parent.parent / "templates" / "code-mower.example.yml",
+        script_path.parents[1] / "code-mower.example.yml",
+    ]
+
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+    return path
+
+
+def resolve_doctor_config_path(
+    config_arg: str,
+    *,
+    easy: bool = False,
+    script_path: Path | None = None,
+) -> Path:
+    return resolve_doctor_config_path_for_script(
+        config_arg,
+        easy=easy,
+        script_path=script_path or Path(__file__),
+    )
+
+
+def resolve_doctor_provider_templates_path(path_text: str) -> Path:
+    path = Path(path_text)
+    if path_text == code_mower_package.DEFAULT_PROVIDER_TEMPLATES and not path.is_absolute():
+        project_catalog = Path.cwd() / code_mower_package.DEFAULT_PROVIDER_TEMPLATES
+        if project_catalog.exists():
+            return project_catalog
+    return code_mower_package.resolve_provider_templates_path(path_text)
+
+
+def apply_first_run_defaults(args: Namespace) -> None:
+    if not (getattr(args, "v05", False) or getattr(args, "preflight", False)):
+        return
+    args.easy = True
+    if args.profile is None:
+        args.profile = "recommended"
+    args.probe_runtime = True
+    args.github = True
+    args.cloud = True

code_mower/doctor_checks/privacy.py

@@ -0,0 +1,20 @@
+"""Privacy-preserving doctor output helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def auth_probe_output_detail(output: str) -> dict[str, Any]:
+    """Return non-content diagnostics for auth probes.
+
+    Doctor probes sometimes receive provider auth output containing account
+    names, emails, scopes, or token-adjacent diagnostics. Keep only shape
+    metadata so reports can explain that output existed without storing it.
+    """
+
+    text = output.strip()
+    return {
+        "output_redacted": bool(text),
+        "output_line_count": len(text.splitlines()) if text else 0,
+    }

code_mower/doctor_checks/provider_api_model.py

@@ -0,0 +1,138 @@
+"""Provider API-model profile checks and probe orchestration."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+from typing import Any, Mapping
+
+from .common import (
+    DoctorCheck,
+    STATUS_FAIL,
+    STATUS_PASS,
+    STATUS_SKIP,
+    STATUS_WARN,
+)
+from .provider_api_model_openai import fetch_openai_compatible_models
+from .provider_api_model_profiles import (
+    api_model_key,
+    local_llm_lane_profiles,
+    runtime_profile,
+)
+
+
+def check_api_model(
+    lane_id: str,
+    lane: Mapping[str, Any],
+    *,
+    probe_runtime: bool,
+    http_timeout: int,
+) -> list[DoctorCheck]:
+    checks: list[DoctorCheck] = []
+    try:
+        profiles = local_llm_lane_profiles(lane)
+    except (TypeError, ValueError) as exc:
+        checks.append(
+            DoctorCheck(
+                name="runtime.api_model.profiles",
+                status=STATUS_FAIL,
+                lane=lane_id,
+                message=str(exc),
+                remediation=(
+                    "Fix provider_config.profiles in code-mower.yml or use a "
+                    "known packaged local LLM profile id."
+                ),
+            )
+        )
+        return checks
+    if not profiles:
+        checks.append(
+            DoctorCheck(
+                name="runtime.api_model.profiles",
+                status=STATUS_WARN,
+                lane=lane_id,
+                message="no API model profiles configured",
+                remediation=(
+                    "Add provider_config.profiles to this lane or select a "
+                    "packaged local LLM profile."
+                ),
+            )
+        )
+        return checks
+
+    checks.append(
+        DoctorCheck(
+            name="runtime.api_model.profiles",
+            status=STATUS_PASS,
+            lane=lane_id,
+            message=f"{len(profiles)} API model profile(s) configured",
+            detail={"profiles": [profile.profile_id for profile in profiles]},
+        )
+    )
+    if not probe_runtime:
+        checks.append(
+            DoctorCheck(
+                name="runtime.api_model.probe",
+                status=STATUS_SKIP,
+                lane=lane_id,
+                message="runtime probing skipped; pass --probe-runtime to query model endpoints",
+            )
+        )
+        return checks
+
+    for profile in profiles:
+        runtime = runtime_profile(lane, profile)
+        try:
+            models = fetch_openai_compatible_models(
+                runtime.api_base,
+                api_model_key(lane, profile),
+                http_timeout,
+            )
+        except (OSError, ValueError, urllib.error.URLError, json.JSONDecodeError) as exc:
+            checks.append(
+                DoctorCheck(
+                    name="runtime.api_model.probe",
+                    status=STATUS_WARN,
+                    lane=lane_id,
+                    message=f"{runtime.profile_id} probe failed: {exc}",
+                    detail={
+                        "profile": runtime.profile_id,
+                        "api_base": runtime.api_base,
+                    },
+                    remediation=(
+                        "Start the local OpenAI-compatible endpoint, fix api_base "
+                        "or api key overrides, then rerun doctor --probe-runtime."
+                    ),
+                )
+            )
+            continue
+        expected = runtime.model
+        status = STATUS_PASS if expected in models else STATUS_WARN
+        message = (
+            f"{runtime.profile_id} reports expected model {expected}"
+            if status == STATUS_PASS
+            else f"{runtime.profile_id} did not report expected model {expected}"
+        )
+        checks.append(
+            DoctorCheck(
+                name="runtime.api_model.probe",
+                status=status,
+                lane=lane_id,
+                message=message,
+                detail={
+                    "profile": runtime.profile_id,
+                    "api_base": runtime.api_base,
+                    "expected_model": expected,
+                    "models": models,
+                },
+                remediation=(
+                    None
+                    if status == STATUS_PASS
+                    else (
+                        "Update the configured local LLM model or start an endpoint "
+                        "that serves the expected model."
+                    )
+                ),
+            )
+        )
+    return checks

code_mower/doctor_checks/provider_api_model_openai.py

@@ -0,0 +1,29 @@
+"""OpenAI-compatible provider API-model probes."""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from typing import Mapping
+
+
+def fetch_openai_compatible_models(
+    api_base: str,
+    api_key: str,
+    timeout: int,
+) -> list[str]:
+    request = urllib.request.Request(
+        f"{api_base.rstrip('/')}/models",
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        },
+    )
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        payload = json.loads(response.read().decode("utf-8"))
+    data = payload.get("data", []) if isinstance(payload, Mapping) else []
+    return [
+        str(entry.get("id"))
+        for entry in data
+        if isinstance(entry, Mapping) and entry.get("id")
+    ]

code_mower/doctor_checks/provider_api_model_profiles.py

@@ -0,0 +1,137 @@
+"""Provider API-model profile expansion and runtime overrides."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Mapping
+
+from .common import local_llm_profiles
+
+
+def profile_from_config(
+    profile_id: str, raw: Mapping[str, Any]
+) -> local_llm_profiles.LocalLlmProfile:
+    canonical = local_llm_profiles.LOCAL_LLM_PROFILES.get(profile_id)
+
+    def profile_int(field: str, default: int) -> int:
+        value = raw.get(field, default)
+        try:
+            return int(value)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(
+                f"API model profile {profile_id!r} field {field!r} must be an integer"
+            ) from exc
+
+    return local_llm_profiles.LocalLlmProfile(
+        profile_id=profile_id,
+        description=str(
+            raw.get(
+                "description",
+                canonical.description if canonical else f"{profile_id} local LLM profile",
+            )
+        ),
+        api_base=str(raw.get("api_base", canonical.api_base if canonical else "")),
+        model=str(raw.get("model", canonical.model if canonical else "")),
+        endpoint=str(raw.get("endpoint", canonical.endpoint if canonical else "")),
+        api_key=str(raw.get("api_key", canonical.api_key if canonical else "EMPTY")),
+        context_window=profile_int(
+            "context_window", canonical.context_window if canonical else 128_000
+        ),
+        max_files=profile_int("max_files", canonical.max_files if canonical else 25),
+        max_file_bytes=profile_int(
+            "max_file_bytes", canonical.max_file_bytes if canonical else 60_000
+        ),
+        http_timeout=profile_int("http_timeout", canonical.http_timeout if canonical else 900),
+        informational=bool(
+            raw.get("informational", canonical.informational if canonical else True)
+        ),
+    )
+
+
+def local_llm_lane_profiles(
+    lane: Mapping[str, Any],
+) -> tuple[local_llm_profiles.LocalLlmProfile, ...]:
+    provider_config = lane.get("provider_config", {})
+    if not isinstance(provider_config, Mapping):
+        return ()
+    raw_profiles = provider_config.get("profiles", {})
+    profile_env = str(provider_config.get("profile_env", ""))
+    selected_profile_id = os.environ.get(profile_env) if profile_env else None
+    if selected_profile_id:
+        if isinstance(raw_profiles, Mapping):
+            raw_profile = raw_profiles.get(selected_profile_id)
+            if isinstance(raw_profile, Mapping):
+                return (profile_from_config(selected_profile_id, raw_profile),)
+        try:
+            return (local_llm_profiles.get_profile(selected_profile_id),)
+        except KeyError:
+            return ()
+    if isinstance(raw_profiles, Mapping):
+        return tuple(
+            profile_from_config(str(profile_id), profile)
+            for profile_id, profile in sorted(raw_profiles.items())
+            if isinstance(profile, Mapping)
+        )
+    if isinstance(raw_profiles, (list, tuple)):
+        profiles: list[local_llm_profiles.LocalLlmProfile] = []
+        for profile_id in raw_profiles:
+            try:
+                profiles.append(local_llm_profiles.get_profile(str(profile_id)))
+            except KeyError:
+                continue
+        return tuple(profiles)
+    return ()
+
+
+def api_model_key(
+    lane: Mapping[str, Any], profile: local_llm_profiles.LocalLlmProfile
+) -> str:
+    provider_config = lane.get("provider_config", {})
+    api_key_env = ""
+    if isinstance(provider_config, Mapping):
+        api_key_env = str(provider_config.get("api_key_env", ""))
+    token_env = lane.get("token_env", [])
+    if not api_key_env and isinstance(token_env, list):
+        for item in token_env:
+            name = str(item)
+            if name.endswith("_API_KEY"):
+                api_key_env = name
+                break
+    if api_key_env:
+        value = os.environ.get(api_key_env)
+        if value:
+            return value
+    return profile.api_key
+
+
+def provider_env_override(
+    provider_config: Mapping[str, Any],
+    env_key: str,
+    fallback: str,
+) -> str:
+    env_name = str(provider_config.get(env_key, ""))
+    if not env_name:
+        return fallback
+    return os.environ.get(env_name) or fallback
+
+
+def runtime_profile(
+    lane: Mapping[str, Any],
+    profile: local_llm_profiles.LocalLlmProfile,
+) -> local_llm_profiles.LocalLlmProfile:
+    provider_config = lane.get("provider_config", {})
+    if not isinstance(provider_config, Mapping):
+        return profile
+    return local_llm_profiles.LocalLlmProfile(
+        profile_id=profile.profile_id,
+        description=profile.description,
+        api_base=provider_env_override(provider_config, "api_base_env", profile.api_base),
+        model=provider_env_override(provider_config, "model_env", profile.model),
+        endpoint=profile.endpoint,
+        api_key=profile.api_key,
+        context_window=profile.context_window,
+        max_files=profile.max_files,
+        max_file_bytes=profile.max_file_bytes,
+        http_timeout=profile.http_timeout,
+        informational=profile.informational,
+    )

code_mower/doctor_checks/provider_env.py

@@ -0,0 +1,113 @@
+"""Provider environment and token checks."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .common import (
+    DoctorCheck,
+    STATUS_PASS,
+    STATUS_SKIP,
+    STATUS_WARN,
+    token_remediation,
+)
+from .provider_env_required import provider_required_env_status
+from .provider_env_tokens import provider_token_status
+
+
+def check_token_env(lane_id: str, lane: Mapping[str, Any]) -> list[DoctorCheck]:
+    token_status = provider_token_status(lane)
+    checks: list[DoctorCheck] = []
+    if not token_status.declares_tokens:
+        checks.append(
+            DoctorCheck(
+                name="env.tokens",
+                status=STATUS_SKIP,
+                lane=lane_id,
+                message="lane declares no token env vars",
+            )
+        )
+        return checks
+
+    missing = list(token_status.missing)
+    missing_any = [list(group) for group in token_status.missing_any]
+    token_file_env = list(token_status.token_file_env)
+    if missing or missing_any:
+        messages = []
+        if missing:
+            messages.append(f"missing token env vars: {', '.join(missing)}")
+        for group in missing_any:
+            messages.append(f"set one of: {', '.join(group)}")
+        checks.append(
+            DoctorCheck(
+                name="env.tokens",
+                status=STATUS_WARN,
+                lane=lane_id,
+                message="; ".join(messages),
+                detail={
+                    "missing": missing,
+                    "missing_any": missing_any,
+                    "token_file_env": token_file_env,
+                },
+                remediation=token_remediation(missing, missing_any),
+            )
+        )
+    else:
+        checks.append(
+            DoctorCheck(
+                name="env.tokens",
+                status=STATUS_PASS,
+                lane=lane_id,
+                message="token env vars are set",
+                detail={
+                    "token_env": list(token_status.token_env),
+                    "token_env_any": [list(group) for group in token_status.token_env_any],
+                    "token_file_env": token_file_env,
+                },
+            )
+        )
+    return checks
+
+
+def check_required_env(lane_id: str, lane: Mapping[str, Any]) -> list[DoctorCheck]:
+    env_status = provider_required_env_status(lane)
+    if not env_status.declares_required_env:
+        return []
+    required = list(env_status.required)
+    required_truthy = list(env_status.required_truthy)
+    missing = list(env_status.missing)
+    missing_truthy = list(env_status.missing_truthy)
+    if missing or missing_truthy:
+        return [
+            DoctorCheck(
+                name="env.required",
+                status=STATUS_WARN,
+                lane=lane_id,
+                message=(
+                    "missing required env vars: "
+                    + ", ".join([*missing, *missing_truthy])
+                ),
+                detail={
+                    "missing": missing,
+                    "missing_truthy": missing_truthy,
+                    "required_env": required,
+                    "required_env_truthy": required_truthy,
+                },
+                remediation=(
+                    "Set the required env vars only when you accept the lane's "
+                    "documented runtime trust model."
+                ),
+            )
+        ]
+    return [
+        DoctorCheck(
+            name="env.required",
+            status=STATUS_PASS,
+            lane=lane_id,
+            message="required env vars are set",
+            detail={
+                "required_env": required,
+                "required_env_truthy": required_truthy,
+            },
+        )
+    ]

code_mower/doctor_checks/provider_env_required.py

@@ -0,0 +1,56 @@
+"""Provider required environment status helpers."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from .common import TRUTHY_ENV_VALUES, as_sequence
+
+
+@dataclass(frozen=True)
+class ProviderRequiredEnvStatus:
+    required: tuple[str, ...]
+    required_truthy: tuple[str, ...]
+    missing: tuple[str, ...]
+    missing_truthy: tuple[str, ...]
+
+    @property
+    def declares_required_env(self) -> bool:
+        return bool(self.required or self.required_truthy)
+
+    @property
+    def all_present(self) -> bool:
+        return not self.missing and not self.missing_truthy
+
+
+def provider_required_env_status(lane: Mapping[str, Any]) -> ProviderRequiredEnvStatus:
+    provider_config = lane.get("provider_config", {})
+    if not isinstance(provider_config, Mapping):
+        return ProviderRequiredEnvStatus((), (), (), ())
+    required = tuple(
+        str(name)
+        for name in as_sequence(provider_config.get("required_env", []))
+        if str(name).strip()
+    )
+    required_truthy = tuple(
+        str(name)
+        for name in as_sequence(provider_config.get("required_env_truthy", []))
+        if str(name).strip()
+    )
+    missing = tuple(name for name in required if not os.environ.get(name))
+    missing_truthy = tuple(
+        name
+        for name in required_truthy
+        if os.environ.get(name, "").strip().lower() not in TRUTHY_ENV_VALUES
+    )
+    return ProviderRequiredEnvStatus(
+        required=required,
+        required_truthy=required_truthy,
+        missing=missing,
+        missing_truthy=missing_truthy,
+    )
+
+
+__all__ = ["ProviderRequiredEnvStatus", "provider_required_env_status"]