cursorfleet 0.1.0__py3-none-any.whl

cursorfleet/adapters/cursor/validation.py

@@ -0,0 +1,365 @@
+"""``cursorfleet validate``: check config, roster, generated kit and artifacts.
+
+Read-only. Findings about files CursorFleet generated are errors; findings
+about user-owned files (their own rules or agents) are warnings, because we
+cannot know what Cursor accepts beyond what the docs say. PROVISIONAL: the
+allowed frontmatter keys come from the Cursor docs (ADR 0001 A7), not a live run.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Literal
+
+from pydantic import ValidationError
+
+from cursorfleet.adapters.cursor import blocks
+from cursorfleet.adapters.cursor.fsutil import (
+    UnsafePathError,
+    ensure_inside,
+    is_link_like,
+    read_text,
+    sha256_text,
+)
+from cursorfleet.adapters.cursor.installer import check_drift, read_lock
+from cursorfleet.adapters.cursor.kit import (
+    AGENTS_DIR,
+    CONFIG_PATH,
+    LOCK_PATH,
+    ROSTER_PATH,
+    RULES_DIR,
+    SKILLS_DIR,
+    SUBAGENT_FRONTMATTER_KEYS,
+    build_kit,
+)
+from cursorfleet.config.io import loads_config, loads_roster
+from cursorfleet.config.models import FleetConfig
+from cursorfleet.config.roster import Roster, default_roster
+from cursorfleet.workflow.artifacts import MAX_ARTIFACT_BYTES, validate_artifact_text
+from cursorfleet.workflow.frontmatter import FrontmatterError, parse_frontmatter
+
+Severity = Literal["error", "warning"]
+RULE_KEYS: frozenset[str] = frozenset({"description", "globs", "alwaysApply"})
+SKILL_KEYS: frozenset[str] = frozenset({"name", "description"})
+MAX_RULE_LINES = 500  # rules must stay strictly under this
+MAX_ARTIFACT_FILES = 2000
+
+
+@dataclass(frozen=True)
+class Finding:
+    severity: Severity
+    code: str
+    message: str
+    path: str | None = None
+    hint: str | None = None
+
+    def as_dict(self) -> dict[str, str | None]:
+        return {
+            "severity": self.severity,
+            "code": self.code,
+            "path": self.path,
+            "message": self.message,
+            "hint": self.hint,
+        }
+
+
+def _first_line(exc: Exception) -> str:
+    return (str(exc).strip().splitlines() or ["error"])[0][:200]
+
+
+class _Validator:
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self.findings: list[Finding] = []
+
+    def add(
+        self,
+        severity: Severity,
+        code: str,
+        message: str,
+        path: str | None = None,
+        hint: str | None = None,
+    ) -> None:
+        self.findings.append(Finding(severity, code, message, path, hint))
+
+    def read(self, rel: str) -> str | None:
+        try:
+            return read_text(ensure_inside(self.root, rel))
+        except (UnsafePathError, ValueError) as exc:
+            self.add("error", "file.unreadable", _first_line(exc), rel)
+            return None
+
+    # -- config and roster ---------------------------------------------------------
+
+    def load_config(self) -> FleetConfig | None:
+        text = self.read(CONFIG_PATH)
+        if text is None:
+            return FleetConfig() if not self._has(CONFIG_PATH) else None
+        try:
+            return loads_config(text)
+        except (ValueError, ValidationError) as exc:
+            self.add(
+                "error",
+                "config.invalid",
+                _first_line(exc),
+                CONFIG_PATH,
+                "Fix the value or delete the file and re-run `cursorfleet init --cursor`.",
+            )
+            return None
+
+    def load_roster(self) -> Roster | None:
+        text = self.read(ROSTER_PATH)
+        if text is None:
+            return default_roster() if not self._has(ROSTER_PATH) else None
+        try:
+            return loads_roster(text)
+        except (ValueError, ValidationError) as exc:
+            self.add(
+                "error",
+                "roster.invalid",
+                _first_line(exc),
+                ROSTER_PATH,
+                "Fix the roster (ids are unique slugs; the coordinator is not a subagent).",
+            )
+            return None
+
+    def _has(self, rel: str) -> bool:
+        return self.root.joinpath(*rel.split("/")).exists()
+
+    def check_roster(self, roster: Roster) -> None:
+        names = [roster.cursor_name(a.id) for a in roster.agents]
+        if len(set(names)) != len(names):
+            self.add("error", "roster.duplicate_names", "two agents share a Cursor subagent name")
+        if not roster.enabled_agents():
+            self.add("warning", "roster.empty", "no subagent is enabled", ROSTER_PATH)
+        coordinator_file = f"{AGENTS_DIR}/{roster.cursor_name('coordinator')}.md"
+        if self._has(coordinator_file):
+            self.add(
+                "error",
+                "roster.coordinator_as_subagent",
+                "the coordinator must be the main agent (a skill), not a subagent file",
+                coordinator_file,
+                "Delete the file; the cursorfleet-coordinator skill delivers the coordinator.",
+            )
+
+    # -- generated kit -------------------------------------------------------------
+
+    def check_kit(self, roster: Roster, config: FleetConfig) -> set[str]:  # noqa: PLR0912
+        """Compare disk with the rendered kit. Returns the set of kit-owned file paths."""
+        lock_errors: list[str] = []
+        lock = read_lock(self.root, lock_errors)
+        for err in lock_errors:
+            self.add("error", "lock.invalid", err, LOCK_PATH)
+        kit = build_kit(roster, config)
+        installed = lock is not None or any(self._has(p) for p in kit.files)
+        if not installed:
+            self.add(
+                "warning",
+                "kit.not_installed",
+                "the CursorFleet kit is not installed",
+                None,
+                "Run `cursorfleet init --cursor`.",
+            )
+            return set(kit.files)
+        for rel, desired in kit.files.items():
+            disk = self.read(rel)
+            if disk is None:
+                if not any(f.path == rel and f.code == "file.unreadable" for f in self.findings):
+                    self.add(
+                        "error",
+                        "kit.missing",
+                        "generated file is missing",
+                        rel,
+                        "Run `cursorfleet init --cursor` to regenerate it.",
+                    )
+            elif sha256_text(disk) != sha256_text(desired):
+                self.add(
+                    "error",
+                    "kit.drift",
+                    "file differs from what the templates and roster generate",
+                    rel,
+                    "Edit the roster instead of the file, then re-run `cursorfleet init --cursor`.",
+                )
+        for rel, block in kit.blocks.items():
+            disk = self.read(rel)
+            try:
+                current = blocks.block_text(disk) if disk is not None else None
+            except blocks.BlockError as exc:
+                self.add("error", "kit.block_malformed", str(exc), rel)
+                continue
+            if current is None:
+                self.add("error", "kit.block_missing", "managed block is missing", rel)
+            elif sha256_text(current) != sha256_text(block):
+                self.add("error", "kit.block_drift", "managed block differs from template", rel)
+        if lock is not None:
+            for item in check_drift(self.root, lock):
+                if item.is_problem and item.kind == "hooks":
+                    self.add("error", "kit.hooks_drift", item.detail, item.path)
+            for entry in lock.files:
+                if entry.kind == "file" and entry.path not in kit.files:
+                    self.add(
+                        "warning",
+                        "kit.orphan",
+                        "installed file is no longer generated by the roster",
+                        entry.path,
+                        "Re-run `cursorfleet init --cursor` to remove it.",
+                    )
+        return set(kit.files)
+
+    # -- frontmatter checks --------------------------------------------------------
+
+    def check_agents(self, roster: Roster, kit_files: set[str]) -> None:
+        base = self.root / AGENTS_DIR
+        if not base.is_dir() or is_link_like(base):
+            return
+        for entry in sorted(base.iterdir(), key=lambda p: p.name):
+            rel = f"{AGENTS_DIR}/{entry.name}"
+            if rel not in kit_files and not entry.name.startswith(roster.name_prefix or "\0"):
+                continue
+            text = self.read(rel)
+            if text is None:
+                continue
+            try:
+                meta = parse_frontmatter(text).meta
+            except FrontmatterError as exc:
+                self.add("error", "agent.frontmatter", str(exc), rel)
+                continue
+            extra = sorted(set(meta) - set(SUBAGENT_FRONTMATTER_KEYS))
+            if extra:
+                self.add(
+                    "error",
+                    "agent.frontmatter_key",
+                    f"unsupported subagent frontmatter keys: {', '.join(extra)}",
+                    rel,
+                    f"Cursor supports only: {', '.join(SUBAGENT_FRONTMATTER_KEYS)}.",
+                )
+            for key in ("name", "description"):
+                if not isinstance(meta.get(key), str) or not meta.get(key):
+                    self.add("error", "agent.frontmatter_missing", f"missing {key}", rel)
+            for key in ("readonly", "is_background"):
+                if key in meta and not isinstance(meta[key], bool):
+                    self.add("error", "agent.frontmatter_type", f"{key} must be true/false", rel)
+            if meta.get("name") != PurePosixPath(entry.name).stem:
+                self.add("error", "agent.name_mismatch", "name must equal the file name", rel)
+
+    def check_rules(self, kit_files: set[str]) -> None:
+        base = self.root / RULES_DIR
+        if not base.is_dir() or is_link_like(base):
+            return
+        for dirpath, dirnames, filenames in os.walk(base, followlinks=False):
+            dirnames.sort()
+            for name in sorted(filenames):
+                full = Path(dirpath) / name
+                rel = full.relative_to(self.root).as_posix()
+                ours = rel in kit_files
+                sev: Severity = "error" if ours else "warning"
+                if full.suffix != ".mdc":
+                    self.add(
+                        sev,
+                        "rules.extension",
+                        "rule files must be .mdc; Cursor ignores other extensions here",
+                        rel,
+                        "Rename to .mdc and add frontmatter.",
+                    )
+                    continue
+                self._check_rule(rel, sev)
+
+    def _check_rule(self, rel: str, sev: Severity) -> None:
+        text = self.read(rel)
+        if text is None:
+            return
+        if len(text.splitlines()) >= MAX_RULE_LINES:
+            self.add(sev, "rules.too_long", f"rule has {MAX_RULE_LINES} or more lines", rel)
+        try:
+            meta = parse_frontmatter(text).meta
+        except FrontmatterError as exc:
+            self.add(sev, "rules.frontmatter", str(exc), rel, "Add a `---` frontmatter block.")
+            return
+        extra = sorted(set(meta) - RULE_KEYS)
+        if extra:
+            self.add(
+                "warning",
+                "rules.frontmatter_key",
+                f"unrecognized rule keys: {', '.join(extra)}",
+                rel,
+            )
+        if "alwaysApply" in meta and not isinstance(meta["alwaysApply"], bool):
+            self.add(sev, "rules.frontmatter_type", "alwaysApply must be true/false", rel)
+
+    def check_skills(self, kit_files: set[str]) -> None:
+        for rel in sorted(p for p in kit_files if p.startswith(SKILLS_DIR + "/")):
+            if not self._has(rel):
+                continue
+            text = self.read(rel)
+            if text is None:
+                continue
+            try:
+                meta = parse_frontmatter(text).meta
+            except FrontmatterError as exc:
+                self.add("error", "skill.frontmatter", str(exc), rel)
+                continue
+            extra = sorted(set(meta) - SKILL_KEYS)
+            if extra:
+                self.add("error", "skill.frontmatter_key", f"unsupported: {', '.join(extra)}", rel)
+            if meta.get("name") != PurePosixPath(rel).parent.name:
+                self.add("error", "skill.name_mismatch", "name must equal the directory", rel)
+            if not isinstance(meta.get("description"), str) or not meta.get("description"):
+                self.add("error", "skill.frontmatter_missing", "missing description", rel)
+
+    # -- artifacts -----------------------------------------------------------------
+
+    def check_artifacts(self, config: FleetConfig) -> int:
+        work_rel = config.work.dir
+        base = self.root.joinpath(*work_rel.split("/"))
+        if not base.is_dir() or is_link_like(base):
+            return 0
+        count = 0
+        for dirpath, dirnames, filenames in os.walk(base, followlinks=False):
+            dirnames.sort()
+            for name in sorted(filenames):
+                full = Path(dirpath) / name
+                inner = full.relative_to(base).as_posix()
+                rel = f"{work_rel}/{inner}"
+                if not name.endswith(".md") or name == "AGENTS.md":
+                    continue
+                count += 1
+                if count > MAX_ARTIFACT_FILES:
+                    self.add("warning", "artifact.too_many", "stopped after 2000 artifacts")
+                    return count
+                if is_link_like(full):
+                    self.add("warning", "artifact.symlink", "symlink skipped", rel)
+                    continue
+                try:
+                    if full.stat().st_size > MAX_ARTIFACT_BYTES:
+                        self.add("error", "artifact.too_large", "artifact is too large", rel)
+                        continue
+                except OSError:
+                    continue
+                text = self.read(rel)
+                if text is None:
+                    continue
+                for problem in validate_artifact_text(text, inner):
+                    self.add("error", problem.code, problem.message, rel)
+        return count
+
+
+def validate_workspace(root: Path) -> tuple[list[Finding], dict[str, int]]:
+    """Run every check. Returns ``(findings, stats)``."""
+    v = _Validator(root)
+    config = v.load_config()
+    roster = v.load_roster()
+    artifacts = 0
+    if roster is not None:
+        v.check_roster(roster)
+    if roster is not None and config is not None:
+        kit_files = v.check_kit(roster, config)
+        v.check_agents(roster, kit_files)
+        v.check_skills(kit_files)
+        v.check_rules(kit_files)
+    else:
+        v.check_rules(set())
+    artifacts = v.check_artifacts(config or FleetConfig())
+    stats = {"artifacts": artifacts}
+    return v.findings, stats

cursorfleet/adapters/cursor/workspace.py

@@ -0,0 +1,80 @@
+"""Resolve the workspace root and the shared runtime directory via git (ADR 0002).
+
+Every subprocess uses an argv list and an explicit timeout.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from cursorfleet.git.runner import git_env
+from cursorfleet.safeexe import find_executable
+
+GIT_TIMEOUT_S = 10.0
+
+
+class WorkspaceError(RuntimeError):
+    """The path is not inside a usable git repository."""
+
+
+@dataclass(frozen=True)
+class Workspace:
+    root: Path  # top level of the working tree (a worktree root inside a worktree)
+    common_dir: Path  # absolute, realpath-resolved ``git rev-parse --git-common-dir``
+
+    @property
+    def runtime_dir(self) -> Path:
+        """``<git-common-dir>/cursorfleet`` (shared by all worktrees; PROVISIONAL, ADR 0002 Q4)."""
+        return self.common_dir / "cursorfleet"
+
+
+def run_git(args: list[str], cwd: Path, *, timeout: float = GIT_TIMEOUT_S) -> str:
+    """Run ``git <args>`` read-only in ``cwd`` and return stdout. Raises ``WorkspaceError``."""
+    git = find_executable("git")  # never the current directory (hostile repositories)
+    if git is None:
+        msg = "git was not found on PATH"
+        raise WorkspaceError(msg)
+    try:
+        proc = subprocess.run(  # noqa: S603
+            [git, "--no-optional-locks", "-c", "core.fsmonitor=false", *args],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+            check=False,
+            env=git_env(),
+            stdin=subprocess.DEVNULL,
+        )
+    except subprocess.TimeoutExpired as exc:
+        msg = f"git {args[0]} timed out after {timeout:g}s"
+        raise WorkspaceError(msg) from exc
+    except OSError as exc:
+        msg = f"cannot run git: {exc.strerror or exc}"
+        raise WorkspaceError(msg) from exc
+    if proc.returncode != 0:
+        first = (proc.stderr.strip().splitlines() or ["unknown error"])[0]
+        msg = f"git {args[0]} failed: {first[:200]}"
+        raise WorkspaceError(msg)
+    return proc.stdout
+
+
+def resolve_workspace(path: Path) -> Workspace:
+    """Return the :class:`Workspace` containing ``path``. Raises ``WorkspaceError``."""
+    start = path.resolve()
+    if not start.is_dir():
+        msg = f"{path} is not a directory"
+        raise WorkspaceError(msg)
+    out = run_git(["rev-parse", "--show-toplevel", "--git-common-dir"], start)
+    lines = out.splitlines()
+    if len(lines) != 2:
+        msg = "unexpected output from git rev-parse"
+        raise WorkspaceError(msg)
+    top = Path(lines[0])
+    common = Path(lines[1])
+    if not common.is_absolute():
+        common = start / common
+    return Workspace(root=top.resolve(), common_dir=common.resolve())

cursorfleet/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""One module per command group; each exposes ``register(app: typer.Typer) -> None``."""

cursorfleet/cli/commands/_common.py

@@ -0,0 +1,82 @@
+"""Helpers shared by the kit commands (init, uninstall, doctor, validate)."""
+
+from __future__ import annotations
+
+import os
+import shlex
+from pathlib import Path
+
+import typer
+
+from cursorfleet.adapters.cursor.fsutil import safe_text
+from cursorfleet.adapters.cursor.installer import Plan, render_diff, summarize
+from cursorfleet.adapters.cursor.workspace import WorkspaceError, resolve_workspace
+from cursorfleet.state.runtime import find_git_location
+
+
+def fail(message: str, code: int = 1) -> typer.Exit:
+    typer.echo(safe_text(message), err=True)
+    return typer.Exit(code)
+
+
+def _looks_like_git_dir(path: Path) -> bool:
+    return (path / "HEAD").is_file() and (path / "objects").is_dir()
+
+
+def _suggested_command(command: str, root: Path) -> str:
+    extra = " --cursor" if command == "init" else ""
+    return f"cd {shlex.quote(str(root))} && cursorfleet {command}{extra}"
+
+
+def workspace_root(path: Path, *, command: str = "init") -> Path:
+    """Return ``path`` only when it is a Git repository root (ADR 0009).
+
+    Exits 2 and writes nothing when the target is not a Git working tree or is
+    an ordinary subdirectory. Does not read ``.cursorfleet/`` or build a plan.
+    """
+    try:
+        target = path.expanduser().resolve()
+    except OSError as exc:
+        raise fail(f"error: cannot resolve {path}.\nNothing was changed.", 2) from exc
+    if not target.is_dir():
+        raise fail(
+            f"error: {safe_text(str(target))} is not a directory.\nNothing was changed.",
+            2,
+        )
+    try:
+        workspace = resolve_workspace(target)
+    except WorkspaceError as exc:
+        loc = find_git_location(str(target))
+        if loc is None and not _looks_like_git_dir(target):
+            raise fail(
+                f"error: Git is required. {safe_text(str(target))} is not inside a "
+                "Git working tree.\nNothing was changed. Run `git init` there, or run "
+                "this command from a repository root.",
+                2,
+            ) from exc
+        first = str(exc).splitlines()[0][:200]
+        raise fail(
+            f"error: no usable working tree was found. {safe_text(first)}\nNothing was changed.",
+            2,
+        ) from exc
+    target_key = os.path.normcase(os.path.realpath(str(target)))
+    root_key = os.path.normcase(os.path.realpath(str(workspace.root)))
+    if target_key != root_key:
+        raise fail(
+            f"error: {safe_text(str(target))} is not the repository root.\n"
+            f"Detected repository root: {safe_text(str(workspace.root))}\n"
+            f"Nothing was changed. Run:  {_suggested_command(command, workspace.root)}",
+            2,
+        )
+    return workspace.root
+
+
+def show_plan(plan: Plan) -> None:
+    typer.echo(f"Workspace: {safe_text(str(plan.root))}")
+    typer.echo("Planned changes:")
+    for line in summarize(plan):
+        typer.echo(f"  {line}")
+    for note in plan.notes:
+        typer.echo(f"  note: {safe_text(note)}")
+    typer.echo("")
+    typer.echo(render_diff(plan), nl=False)

cursorfleet/cli/commands/_resolution.py

@@ -0,0 +1,56 @@
+"""Shared doctor/validate repository-resolution renderers (ADR 0009 task 15).
+
+The facts come from ``inspect_repository`` (the Task 16 file-walk). This module
+does not walk, does not write, and keeps JSON and plain text on the same mapping.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cursorfleet.adapters.cursor.fsutil import safe_text
+from cursorfleet.state.runtime import Resolution, inspect_repository
+
+RESOLUTION_KEYS = (
+    "input_path",
+    "resolved_path",
+    "repository_root",
+    "common_dir",
+    "marker_path",
+    "marker_present",
+    "marker_valid",
+    "boundary",
+    "status",
+    "reason",
+)
+
+
+def build_resolution(path: Path, workspace_roots: object = None) -> Resolution:
+    """Read-only classification of ``path``. Never creates files or directories."""
+    try:
+        start = str(path.expanduser())
+    except OSError:
+        start = str(path)
+    return inspect_repository(start, workspace_roots)
+
+
+def resolution_as_dict(resolution: Resolution) -> dict[str, object]:
+    """Stable JSON object. ``render_resolution_text`` prints these same values."""
+    return resolution.as_dict()
+
+
+def _shown(value: object) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return safe_text(str(value))
+
+
+def render_resolution_text(resolution: Resolution) -> str:
+    """Plain-text block with the same facts as :func:`resolution_as_dict`."""
+    data = resolution.as_dict()
+    lines = ["Repository resolution:"]
+    for key in RESOLUTION_KEYS:
+        lines.append(f"  {key}: {_shown(data[key])}")
+    return "\n".join(lines)

cursorfleet/cli/commands/doctor.py

@@ -0,0 +1,81 @@
+"""``cursorfleet doctor``: environment, install and hook diagnostics (read-only)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from cursorfleet.adapters.cursor.diagnostics import DoctorReport, run_doctor
+from cursorfleet.adapters.cursor.fsutil import safe_text
+from cursorfleet.cli.commands._resolution import render_resolution_text
+
+_LABEL = {"ok": "ok  ", "warn": "WARN", "fail": "FAIL", "info": "info"}
+
+
+def _render(report: DoctorReport) -> str:
+    lines: list[str] = []
+    if report.resolution is not None:
+        lines.append(render_resolution_text(report.resolution))
+        lines.append("")
+    for check in report.checks:
+        lines.append(f"[{_LABEL[check.status]}] {check.id}: {safe_text(check.message)}")
+        if check.remediation and check.status in {"warn", "fail"}:
+            lines.append(f"       fix: {safe_text(check.remediation)}")
+        if check.id == "install.drift":
+            for item in check.details.get("drift", []):
+                lines.append(f"       - {safe_text(item['path'])}: {safe_text(item['detail'])}")
+    lines.append("")
+    lines.append("Effective hooks (Cursor merge order: enterprise, team, project, user):")
+    for source in report.hooks:
+        if source.path is None:
+            lines.append(f"  {source.level:<10} {safe_text(source.note or 'n/a')}")
+            continue
+        state = "absent" if not source.exists else ("unreadable" if not source.readable else "ok")
+        total = sum(len(v) for v in source.events.values())
+        lines.append(f"  {source.level:<10} {source.path} ({state}, {total} entries)")
+        if source.error:
+            lines.append(f"             error: {source.error}")
+        for event, entries in source.events.items():
+            for entry in entries:
+                tag = "cursorfleet" if entry["ours"] else "other"
+                lines.append(f"             {event}: [{tag}] {entry['command']}")
+    counts = report.counts()
+    lines.append("")
+    lines.append(
+        f"{counts['ok']} ok, {counts['warn']} warnings, {counts['fail']} problems"
+        + ("" if report.ok else " (exit 1)")
+    )
+    return "\n".join(lines)
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("doctor")
+    def doctor(
+        json_output: Annotated[
+            bool, typer.Option("--json", help="Machine-readable output.")
+        ] = False,
+        path: Annotated[
+            Path, typer.Option("--path", help="Directory inside the git repo (default: current).")
+        ] = Path(),
+        probe_cursor: Annotated[
+            bool,
+            typer.Option(
+                "--probe-cursor/--no-probe-cursor",
+                help="Run `cursor --version` (argv, 5s timeout) to report the Cursor version.",
+            ),
+        ] = True,
+    ) -> None:
+        """Check Python, the hook binary, git, runtime dir, install drift and effective hooks.
+
+        Exit code 0 when no check failed (warnings are fine), 1 otherwise.
+        """
+        report = run_doctor(path, probe_cursor=probe_cursor)
+        if json_output:
+            typer.echo(json.dumps(report.as_dict(), indent=2))
+        else:
+            typer.echo(_render(report))
+        if not report.ok:
+            raise typer.Exit(1)