code-mower 0.5.0b5__py3-none-any.whl

code_mower/doctor.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""Run provider-neutral Code Mower setup and runtime checks."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Sequence
+
+if __package__ in {None, ""}:
+    module_dir = Path(__file__).resolve().parent
+    sys.path.insert(0, str(module_dir.parent))
+    if module_dir.name == "code_mower":  # pragma: no cover - extracted direct CLI.
+        from code_mower import config as code_mower_config
+        from code_mower import doctor_checks as _doctor_checks
+        from code_mower import package as code_mower_package
+    else:
+        from tools import code_mower_config, code_mower_package, doctor_checks as _doctor_checks
+elif __package__ == "tools":
+    from tools import code_mower_config, code_mower_package, doctor_checks as _doctor_checks
+else:  # pragma: no cover - exercised after package extraction.
+    from . import config as code_mower_config
+    from . import doctor_checks as _doctor_checks
+    from . import package as code_mower_package
+
+
+ACTIONS_COST_SAMPLE_DEFAULT = _doctor_checks.ACTIONS_COST_SAMPLE_DEFAULT
+ACTIONS_COST_SAMPLE_MAX = _doctor_checks.ACTIONS_COST_SAMPLE_MAX
+DEFAULT_CLOUD_TOKEN_DIR = _doctor_checks.DEFAULT_CLOUD_TOKEN_DIR
+DEFAULT_CLOUD_TOKEN_ENV = _doctor_checks.DEFAULT_CLOUD_TOKEN_ENV
+STATUS_FAIL = _doctor_checks.STATUS_FAIL
+STATUS_PASS = _doctor_checks.STATUS_PASS
+STATUS_SKIP = _doctor_checks.STATUS_SKIP
+STATUS_WARN = _doctor_checks.STATUS_WARN
+DoctorCheck = _doctor_checks.DoctorCheck
+DoctorReport = _doctor_checks.DoctorReport
+_auth_probe_output_detail = _doctor_checks.auth_probe_output_detail
+_check_cloud_token_surface = _doctor_checks.check_cloud_token_surface
+_evaluate_json_probe = _doctor_checks.evaluate_json_probe
+_local_cli_probe_remediation = _doctor_checks.local_cli_probe_remediation
+render_doctor_text = _doctor_checks.render_doctor_text
+resolve_doctor_config_path = _doctor_checks.resolve_doctor_config_path
+resolve_doctor_config_path_for_script = _doctor_checks.resolve_doctor_config_path_for_script
+resolve_doctor_provider_templates_path = _doctor_checks.resolve_doctor_provider_templates_path
+run_doctor = _doctor_checks.run_doctor
+_token_file_mentions_cloud_token = _doctor_checks.token_file_mentions_cloud_token
+_apply_first_run_defaults = _doctor_checks.apply_first_run_defaults
+
+
+_DOCTOR_COMPAT_EXPORTS = (
+    DEFAULT_CLOUD_TOKEN_DIR,
+    DEFAULT_CLOUD_TOKEN_ENV,
+    STATUS_FAIL,
+    STATUS_PASS,
+    STATUS_SKIP,
+    STATUS_WARN,
+    DoctorCheck,
+    DoctorReport,
+    _auth_probe_output_detail,
+    _check_cloud_token_surface,
+    _evaluate_json_probe,
+    _apply_first_run_defaults,
+    _local_cli_probe_remediation,
+    resolve_doctor_config_path_for_script,
+    resolve_doctor_provider_templates_path,
+    _token_file_mentions_cloud_token,
+)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("config", nargs="?", default="code-mower.yml")
+    parser.add_argument(
+        "--provider-templates",
+        default=code_mower_package.DEFAULT_PROVIDER_TEMPLATES,
+    )
+    parser.add_argument("--profile", default=None)
+    parser.add_argument(
+        "--easy",
+        action="store_true",
+        help=(
+            "first-run alias for --profile recommended; if code-mower.yml is "
+            "absent, use the packaged example config"
+        ),
+    )
+    parser.add_argument(
+        "--v05",
+        action="store_true",
+        help=(
+            "v0.5 early-adopter preset: --easy --profile recommended "
+            "--probe-runtime --github --cloud"
+        ),
+    )
+    parser.add_argument(
+        "--preflight",
+        action="store_true",
+        help=(
+            "friendly alias for the v0.5 first-run preset: --easy "
+            "--profile recommended --probe-runtime --github --cloud"
+        ),
+    )
+    parser.add_argument("--probe-runtime", action="store_true")
+    parser.add_argument(
+        "--github",
+        action="store_true",
+        help="inspect GitHub repo visibility, branch protection, and provider setup hints",
+    )
+    parser.add_argument(
+        "--cloud",
+        action="store_true",
+        help="check optional Code Mower Cloud token setup without reading or printing token values",
+    )
+    parser.add_argument("--http-timeout", type=int, default=5)
+    parser.add_argument(
+        "--actions-cost-sample",
+        type=int,
+        default=ACTIONS_COST_SAMPLE_DEFAULT,
+        help=(
+            "number of recent Actions runs to sample for private-repo cost "
+            f"diagnostics, capped at {ACTIONS_COST_SAMPLE_MAX}"
+        ),
+    )
+    parser.add_argument("--strict", action="store_true")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+
+    _apply_first_run_defaults(args)
+    if args.easy and args.profile is None:
+        args.profile = "recommended"
+
+    try:
+        provider_templates_path = resolve_doctor_provider_templates_path(args.provider_templates)
+        report = run_doctor(
+            config_path=resolve_doctor_config_path(args.config, easy=args.easy),
+            provider_templates_path=provider_templates_path,
+            profile=args.profile,
+            probe_runtime=args.probe_runtime,
+            github=args.github,
+            cloud=args.cloud,
+            http_timeout=args.http_timeout,
+            actions_cost_sample=args.actions_cost_sample,
+        )
+    except code_mower_config.ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps(report.as_dict(), indent=2, sort_keys=True))
+    else:
+        print(render_doctor_text(report), end="")
+    if report.failures:
+        return 1
+    if args.strict and report.warnings:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

code_mower/doctor_checks/__init__.py

@@ -0,0 +1,104 @@
+"""Doctor check registry primitives.
+
+The public CLI remains ``code-mower doctor``. This package keeps the
+check/report data model independent from the large command adapter so runtime,
+GitHub, provider, cloud, and output checks can move behind registries without
+changing the CLI contract.
+"""
+
+from .cloud import (
+    DEFAULT_CLOUD_TOKEN_DIR,
+    DEFAULT_CLOUD_TOKEN_ENV,
+    check_cloud_token_surface,
+    token_file_mentions_cloud_token,
+)
+from .common import (
+    ACTIONS_COST_SAMPLE_DEFAULT,
+    ACTIONS_COST_SAMPLE_MAX,
+    load_inputs,
+)
+from .github import check_github_setup
+from .groups import GROUP_LABELS, doctor_check_group_id
+from .models import (
+    STATUS_FAIL,
+    STATUS_PASS,
+    STATUS_SKIP,
+    STATUS_WARN,
+    DoctorCheck,
+    DoctorReport,
+)
+from .output import doctor_output_group, render_doctor_text
+from .presets import (
+    apply_first_run_defaults,
+    resolve_doctor_config_path,
+    resolve_doctor_config_path_for_script,
+    resolve_doctor_provider_templates_path,
+)
+from .providers import (
+    check_lane_runtime,
+    effective_lane,
+    provider_template_coverage,
+    selected_lanes,
+)
+from .provider_probe import evaluate_json_probe, local_cli_probe_remediation
+from .privacy import auth_probe_output_detail
+from .registry import (
+    DEFAULT_CHECK_GROUPS,
+    BASE_DOCTOR_STAGES,
+    OPTIONAL_DOCTOR_STAGES,
+    DoctorCheckGroup,
+    DoctorCheckStage,
+    build_doctor_run_plan,
+    default_check_group_ids,
+)
+from .runtime import (
+    check_github_auth_surface,
+    check_pytest,
+    check_python_runtime,
+    check_ripgrep,
+)
+from .runner import run_doctor
+
+__all__ = [
+    "DEFAULT_CHECK_GROUPS",
+    "GROUP_LABELS",
+    "BASE_DOCTOR_STAGES",
+    "OPTIONAL_DOCTOR_STAGES",
+    "ACTIONS_COST_SAMPLE_DEFAULT",
+    "ACTIONS_COST_SAMPLE_MAX",
+    "DEFAULT_CLOUD_TOKEN_DIR",
+    "DEFAULT_CLOUD_TOKEN_ENV",
+    "DoctorCheck",
+    "DoctorCheckGroup",
+    "DoctorCheckStage",
+    "DoctorReport",
+    "STATUS_FAIL",
+    "STATUS_PASS",
+    "STATUS_SKIP",
+    "STATUS_WARN",
+    "apply_first_run_defaults",
+    "auth_probe_output_detail",
+    "build_doctor_run_plan",
+    "check_cloud_token_surface",
+    "check_github_auth_surface",
+    "check_github_setup",
+    "check_lane_runtime",
+    "check_pytest",
+    "check_python_runtime",
+    "check_ripgrep",
+    "default_check_group_ids",
+    "doctor_check_group_id",
+    "doctor_output_group",
+    "effective_lane",
+    "evaluate_json_probe",
+    "load_inputs",
+    "local_cli_probe_remediation",
+    "provider_template_coverage",
+    "render_doctor_text",
+    "resolve_doctor_config_path",
+    "resolve_doctor_config_path_for_script",
+    "resolve_doctor_provider_templates_path",
+    "run_doctor",
+    "selected_lanes",
+    "token_file_mentions_cloud_token",
+]

code_mower/doctor_checks/cloud.py

@@ -0,0 +1,129 @@
+"""Code Mower Cloud doctor checks."""
+
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+
+from .models import STATUS_PASS, STATUS_SKIP, STATUS_WARN, DoctorCheck
+
+DEFAULT_CLOUD_TOKEN_ENV = "CODE_MOWER_CLOUD_TOKEN"
+DEFAULT_CLOUD_TOKEN_DIR = Path("~/.config/code-mower/tokens")
+
+
+def token_file_mentions_cloud_token(path: Path, token_env: str) -> bool | None:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped.startswith("export "):
+            stripped = stripped.removeprefix("export ").strip()
+        if stripped.startswith(f"{token_env}="):
+            return True
+    return False
+
+
+def check_cloud_token_surface(
+    *,
+    token_env: str = DEFAULT_CLOUD_TOKEN_ENV,
+    token_dir: Path | None = None,
+) -> DoctorCheck:
+    """Check optional Code Mower Cloud token setup without exposing secrets."""
+
+    if os.environ.get(token_env):
+        return DoctorCheck(
+            name="cloud.token",
+            status=STATUS_PASS,
+            message="Code Mower Cloud token env is set",
+            detail={"token_env": token_env, "source": "env"},
+        )
+
+    directory = (token_dir or DEFAULT_CLOUD_TOKEN_DIR).expanduser()
+    redacted_dir = "~/.config/code-mower/tokens"
+    if not directory.exists():
+        return DoctorCheck(
+            name="cloud.token",
+            status=STATUS_SKIP,
+            message="optional Code Mower Cloud token is not configured",
+            detail={"token_env": token_env, "token_dir": redacted_dir},
+            remediation=(
+                "Cloud upload is optional. To enable it, create or receive a "
+                "developer/team token, then run `code-mower cloud setup "
+                "--token-stdin` and source the generated env file."
+            ),
+        )
+
+    token_files: list[str] = []
+    unreadable_files: list[str] = []
+    insecure_files: list[str] = []
+    for path in sorted(directory.glob("*.env")):
+        has_token = token_file_mentions_cloud_token(path, token_env)
+        if has_token is None:
+            unreadable_files.append(path.name)
+            continue
+        if not has_token:
+            continue
+        token_files.append(path.name)
+        try:
+            mode = stat.S_IMODE(path.stat().st_mode)
+        except OSError:
+            unreadable_files.append(path.name)
+            continue
+        if mode & 0o077:
+            insecure_files.append(path.name)
+
+    if unreadable_files:
+        return DoctorCheck(
+            name="cloud.token",
+            status=STATUS_WARN,
+            message="could not inspect one or more Code Mower Cloud token files",
+            detail={
+                "token_env": token_env,
+                "token_dir": redacted_dir,
+                "unreadable_file_count": len(unreadable_files),
+                "unreadable_files": unreadable_files,
+            },
+            remediation=(
+                "Verify token files under ~/.config/code-mower/tokens are UTF-8 "
+                "env files owned by the current user."
+            ),
+        )
+
+    if not token_files:
+        return DoctorCheck(
+            name="cloud.token",
+            status=STATUS_SKIP,
+            message="optional Code Mower Cloud token file was not found",
+            detail={"token_env": token_env, "token_dir": redacted_dir},
+            remediation=(
+                "Cloud upload is optional. To enable it, run `code-mower cloud "
+                "setup --token-stdin` and source the generated env file."
+            ),
+        )
+
+    detail = {
+        "token_env": token_env,
+        "token_dir": redacted_dir,
+        "token_file_count": len(token_files),
+        "token_files": token_files,
+    }
+    if insecure_files:
+        return DoctorCheck(
+            name="cloud.token",
+            status=STATUS_WARN,
+            message="Code Mower Cloud token file permissions are too broad",
+            detail={**detail, "insecure_files": insecure_files},
+            remediation="Run `chmod 600 ~/.config/code-mower/tokens/*.env`.",
+        )
+
+    return DoctorCheck(
+        name="cloud.token",
+        status=STATUS_PASS,
+        message="Code Mower Cloud token file is configured",
+        detail=detail,
+    )

code_mower/doctor_checks/common.py

@@ -0,0 +1,215 @@
+"""Shared doctor helper functions and dependency shims."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .models import STATUS_FAIL, STATUS_PASS, STATUS_SKIP, STATUS_WARN, DoctorCheck
+
+if __package__ in {None, ""}:
+    module_dir = Path(__file__).resolve().parent
+    sys.path.insert(0, str(module_dir.parents[1]))
+    if module_dir.parent.name == "code_mower":  # pragma: no cover - direct package path.
+        from code_mower import config as code_mower_config
+        from code_mower import local_llm_profiles
+        from code_mower import package as code_mower_package
+        from code_mower import secrets as code_mower_secrets
+    else:  # pragma: no cover - extracted direct CLI path.
+        from tools import (
+            code_mower_config,
+            code_mower_package,
+            code_mower_secrets,
+            local_llm_profiles,
+        )
+elif __package__.startswith("tools"):
+    from .. import (
+        code_mower_config,
+        code_mower_package,
+        code_mower_secrets,
+        local_llm_profiles,
+    )
+else:  # pragma: no cover - exercised after package extraction.
+    from .. import config as code_mower_config
+    from .. import local_llm_profiles
+    from .. import package as code_mower_package
+    from .. import secrets as code_mower_secrets
+
+
+SUPPORTED_TOKEN_FILE_ENV_NAMES = frozenset({"GEMINI_API_KEY", "GOOGLE_API_KEY"})
+TRUTHY_ENV_VALUES = frozenset({"1", "true", "yes", "on"})
+ACTIONS_BILLING_BLOCK_PATTERNS = (
+    "recent account payments have failed",
+    "spending limit needs to be increased",
+)
+ACTIONS_INSPECTABLE_FAILURE_CONCLUSIONS = frozenset(
+    {"failure", "action_required", "timed_out", "startup_failure"}
+)
+MAX_ACTIONS_FAILED_RUNS_TO_INSPECT = 5
+MAX_ACTIONS_FAILED_JOBS_TO_INSPECT = 20
+ACTIONS_COST_SAMPLE_DEFAULT = 100
+ACTIONS_COST_SAMPLE_MAX = 100
+ACTIONS_METADATA_WORKFLOW_MARKERS = (
+    "audit-labeler",
+    "labeler",
+    "clear-stale",
+    "audit-label-cleanup",
+    "devin-audit-bridge",
+)
+
+__all__ = [
+    "ACTIONS_BILLING_BLOCK_PATTERNS",
+    "ACTIONS_COST_SAMPLE_DEFAULT",
+    "ACTIONS_COST_SAMPLE_MAX",
+    "ACTIONS_INSPECTABLE_FAILURE_CONCLUSIONS",
+    "ACTIONS_METADATA_WORKFLOW_MARKERS",
+    "DoctorCheck",
+    "MAX_ACTIONS_FAILED_JOBS_TO_INSPECT",
+    "MAX_ACTIONS_FAILED_RUNS_TO_INSPECT",
+    "STATUS_FAIL",
+    "STATUS_PASS",
+    "STATUS_SKIP",
+    "STATUS_WARN",
+    "SUPPORTED_TOKEN_FILE_ENV_NAMES",
+    "TRUTHY_ENV_VALUES",
+    "as_mapping",
+    "as_sequence",
+    "code_mower_config",
+    "code_mower_package",
+    "code_mower_secrets",
+    "join_names",
+    "load_inputs",
+    "local_cli_remediation",
+    "local_llm_profiles",
+    "token_remediation",
+]
+
+
+def as_mapping(value: Any, name: str) -> Mapping[str, Any]:
+    if isinstance(value, Mapping):
+        return value
+    raise code_mower_config.ConfigError(f"{name} must be a mapping")
+
+
+def as_sequence(value: Any) -> tuple[Any, ...]:
+    if isinstance(value, (list, tuple)):
+        return tuple(value)
+    return ()
+
+
+def join_names(names: Sequence[str]) -> str:
+    return ", ".join(str(name) for name in names)
+
+
+def token_remediation(
+    missing: Sequence[str],
+    missing_any: Sequence[Sequence[str]],
+) -> str:
+    parts: list[str] = []
+    if missing:
+        parts.append(
+            "set "
+            + join_names(missing)
+            + " in your shell or GitHub secret store before enabling this lane"
+        )
+    for group in missing_any:
+        names = [str(name) for name in group]
+        if not names:
+            continue
+        if set(names) & {"GEMINI_API_KEY", "GOOGLE_API_KEY"}:
+            parts.append(
+                "set GEMINI_API_KEY or GOOGLE_API_KEY, or run "
+                "`code-mower init auth gemini` and export GEMINI_API_KEY_FILE"
+            )
+        else:
+            parts.append("set one of " + join_names(names))
+    if not parts:
+        return ""
+    return "; ".join(parts) + "."
+
+
+def local_cli_remediation(commands: Sequence[str], command_env: str = "") -> str:
+    command_text = " or ".join(str(command) for command in commands if command)
+    if not command_text:
+        return (
+            "Configure provider_config.command or a non-empty provider id for "
+            "this lane, then rerun doctor."
+        )
+    if command_env:
+        return (
+            f"Install {command_text}, or set {command_env} to the absolute path "
+            "of the provider CLI, then rerun doctor."
+        )
+    return f"Install {command_text} and ensure it is on PATH, then rerun doctor."
+
+
+def load_inputs(
+    config_path: Path,
+    provider_templates_path: Path,
+) -> tuple[Mapping[str, Any] | None, Mapping[str, Any] | None, list[DoctorCheck]]:
+    checks: list[DoctorCheck] = []
+    config: Mapping[str, Any] | None = None
+    templates: Mapping[str, Any] | None = None
+
+    try:
+        config = code_mower_config.load_config(config_path)
+        issues = code_mower_config.validate_config(config)
+    except (OSError, code_mower_config.ConfigError) as exc:
+        checks.append(
+            DoctorCheck(
+                name="config.load",
+                status=STATUS_FAIL,
+                message=f"cannot load config: {exc}",
+                remediation=(
+                    "Run `code-mower init --easy` to render a starter config, "
+                    "or pass an existing config path to doctor."
+                ),
+            )
+        )
+    else:
+        if issues:
+            checks.append(
+                DoctorCheck(
+                    name="config.validate",
+                    status=STATUS_FAIL,
+                    message=code_mower_config._format_issues(issues),
+                    remediation=(
+                        "Fix the listed config issues or regenerate the starter "
+                        "setup with `code-mower init --easy`."
+                    ),
+                )
+            )
+        else:
+            checks.append(
+                DoctorCheck(
+                    name="config.validate",
+                    status=STATUS_PASS,
+                    message="config validates",
+                )
+            )
+
+    try:
+        templates = code_mower_package.load_provider_templates(provider_templates_path)
+    except (OSError, code_mower_config.ConfigError) as exc:
+        checks.append(
+            DoctorCheck(
+                name="provider_templates.load",
+                status=STATUS_FAIL,
+                message=f"cannot load provider templates: {exc}",
+                remediation=(
+                    "Run from the repository root, install the packaged templates, "
+                    "or pass --provider-templates with a readable catalog path."
+                ),
+            )
+        )
+    else:
+        checks.append(
+            DoctorCheck(
+                name="provider_templates.load",
+                status=STATUS_PASS,
+                message="provider templates load",
+            )
+        )
+
+    return config, templates, checks