qodo-cli 0.4.0__tar.gz → 0.5.0__tar.gz

qodo_cli-0.5.0/.pr_agent.toml

@@ -0,0 +1,26 @@
+# Qodo Merge / PR-Agent configuration for qodo-cli.
+# Docs: https://docs.qodo.ai/qodo-documentation/qodo-merge/configuration/configuration-file
+#
+# Kept minimal on purpose (per Qodo's guidance: only override what you need).
+# The repo's coding conventions live in best_practices.md at the root, which the
+# reviewer auto-references; this file just reinforces a few intentional patterns
+# that an earlier review flagged as false positives.
+
+[pr_reviewer]
+extra_instructions = """
+qodo-cli is an unofficial, community CLI to manage Qodo, built as a
+zero-runtime-dependency, stdlib-only Python package. Intentional patterns (do
+not flag these as issues):
+- Command handlers return a bare 0/1/None for the exit code. The EXIT_* constants
+  in qodo/cli/_errors.py are for CliError codes (the failure path), not for
+  handler return values. `return 0` in a handler is intentional and consistent
+  across every command.
+- Nested argparse subparsers inherit the structured-error parser class via
+  `add_subparsers(parser_class=type(p))` (see qodo/cli/_commands/cli.py). Passing
+  `type(p)` is the established idiom and is equivalent to naming
+  `_CliArgumentParser` directly — it is not a missing parser_class.
+- `qodo review resolve --reply` drives the user's own `gh` with their own auth;
+  the reply text belongs to the caller, so the tool must not auto-append an agent
+  signature.
+See best_practices.md at the repo root for the full conventions.
+"""

{qodo_cli-0.4.0 → qodo_cli-0.5.0}/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-06-17
+
+### Added
+
+- `.pr_agent.toml` + `best_practices.md` at the repo root — the Qodo Merge
+  reviewer config (cite, don't fork). They codify this repo's intentional
+  patterns (bare `return 0` handlers, `parser_class=type(p)` subparser nesting,
+  the mechanics-only `review resolve --reply`) so Qodo reviews accurately and
+  stops raising them as violations.
+- `qodo doctor` now also checks **Qodo setup**, against the current git repo:
+  `.pr_agent.toml` present, `best_practices.md` present, and whether a usable
+  Qodo API key is resolvable for `qodo rules` — `QODO_API_KEY`, else a non-empty
+  `API_KEY` in `~/.qodo/config.json` (a present-but-keyless or malformed file
+  fails the check with guidance, and never throws). These are advisory and each
+  carries a `remediation` that guides an agent through setup. Runs in any repo
+  (not just a source checkout). (Addresses #7.)
+
+### Changed
+
+- `qodo doctor` `healthy` now depends on **error**-severity checks only;
+  `warning`/`info` checks surface guidance without flipping `healthy` or the
+  exit code. Fixes the `claude → CLAUDE.md` drift in the `doctor` explain entry
+  (this repo's backend is `colleague` → `AGENTS.colleague.md`).
+- `learn` now describes `doctor` as "agent-identity invariants + Qodo setup" in
+  both its text and JSON payload, matching `overview` and the explain catalog
+  (self-description stays consistent across the introspection surfaces).
+
 ## [0.4.0] - 2026-06-17
 
 ### Added

{qodo_cli-0.4.0 → qodo_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qodo-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: Community CLI and agent to manage Qodo — the AI code reviewer and Qodo's other agents (requires a Qodo subscription). Unofficial: not affiliated with, authorized, or endorsed by Qodo; the Qodo name and trademark belong to Qodo Ltd.
 Project-URL: Homepage, https://github.com/agentculture/qodo-cli
 Project-URL: Issues, https://github.com/agentculture/qodo-cli/issues

qodo_cli-0.5.0/best_practices.md

@@ -0,0 +1,59 @@
+# Best practices for qodo-cli
+
+Repository-specific coding standards for the Qodo reviewer — and for any agent
+working in this repo. `qodo-cli` is an unofficial, community CLI to manage Qodo,
+built as a **zero-runtime-dependency, stdlib-only** Python package.
+
+These conventions are pinned by the test suite and the agent-first rubric
+(`teken cli doctor . --strict`); please review against them rather than against
+generic defaults.
+
+## Dependencies
+
+- Runtime dependencies must stay empty (`dependencies = []` in `pyproject.toml`).
+  Use only the Python standard library at runtime, and flag any new third-party
+  runtime import. `teken` and the lint/test tools are dev-only.
+
+## Exit codes
+
+- Command handlers return a bare `0` / `1` / `None` for their exit code (`0` is
+  success). The `EXIT_*` constants in `qodo/cli/_errors.py` are for `CliError`
+  codes on the failure path, **not** for handler return values. A bare
+  `return 0` in a handler is intentional and consistent across every command —
+  do not flag it as a magic number.
+
+## Errors and output
+
+- Every failure raises `CliError(code, message, remediation)`; no Python
+  traceback may leak to stderr. Text-mode errors render `error: <msg>` then
+  `hint: <remediation>` (the `hint:` prefix is required).
+- Results go to stdout; errors and diagnostics go to stderr. Never mix the two,
+  in text or `--json` mode. Every command supports `--json`.
+
+## argparse
+
+- Build subparsers with the structured-error parser class. Nested subparsers
+  inherit it via `add_subparsers(parser_class=type(p))` (see
+  `qodo/cli/_commands/cli.py`); passing `type(p)` is the established idiom and is
+  equivalent to naming `_CliArgumentParser` directly — it is not a missing
+  `parser_class`.
+- Add the standard `--json` flag with `add_json_flag()` from `qodo.cli._output`
+  rather than re-declaring the literal.
+
+## The CLI is mechanics-only
+
+- `qodo review resolve --reply` drives the user's own `gh` with their own auth;
+  the reply text belongs to the caller. The tool must not auto-append an agent
+  signature — that would mis-attribute human-authored replies. Signing is the
+  caller's responsibility (an opt-in flag may be added later).
+
+## Cite, don't import
+
+- Behavior derived from `qodo-ai/qodo-skills` and the vendored `.claude/skills/`
+  kit is cited as the source of truth, not forked or vendored into runtime code.
+  Keep `docs/qodo-skills-sources.md` in sync when the upstream contract changes.
+
+## Keep the self-description in sync
+
+- When adding a command, update `learn`, `overview`, and the explain catalog so
+  the rubric and the self-describing text stay consistent.

{qodo_cli-0.4.0 → qodo_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qodo-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "Community CLI and agent to manage Qodo — the AI code reviewer and Qodo's other agents (requires a Qodo subscription). Unofficial: not affiliated with, authorized, or endorsed by Qodo; the Qodo name and trademark belong to Qodo Ltd."
 readme = "README.md"
 license = "MIT"

qodo_cli-0.5.0/qodo/cli/_commands/doctor.py

@@ -0,0 +1,262 @@
+"""``qodo-cli doctor`` — check agent-identity invariants and Qodo setup.
+
+Two groups of checks, reported in one rubric-shaped contract
+``{healthy, checks: [{id, passed, severity, message, remediation}]}``:
+
+* **agent identity** (only in a source checkout with ``culture.yaml``):
+  prompt-file-present + backend-consistency (mirrors ``steward doctor``), plus a
+  ``.claude/skills/`` present check.
+* **Qodo setup** (always, against the current repo): whether the repo carries a
+  Qodo reviewer config (``.pr_agent.toml`` / ``best_practices.md``) and whether
+  client API credentials (``~/.qodo/config.json`` / ``QODO_API_KEY``) are
+  available for ``qodo rules``. These are advisory — their ``remediation`` guides
+  an agent through setting them up.
+
+``healthy`` is true when every **error**-severity check passes; ``warning`` /
+``info`` checks surface guidance without failing the command (so ``doctor`` is
+useful in any repo without hard-failing when optional configs are absent).
+Read-only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+
+from qodo.cli._commands.whoami import find_culture_yaml, read_agent_fields
+from qodo.cli._output import add_json_flag, emit_result
+
+# backend → required prompt file (the backend-consistency mapping).
+_PROMPT_FILE = {
+    "claude": "CLAUDE.md",
+    "colleague": "AGENTS.colleague.md",
+    "acp": "AGENTS.md",
+    "gemini": "GEMINI.md",
+}
+
+_CONFIG_DOCS = "https://docs.qodo.ai/qodo-documentation/qodo-merge/configuration/configuration-file"
+_BEST_PRACTICES_DOCS = "https://qodo-merge-docs.qodo.ai/core-abilities/auto_best_practices/"
+
+
+def _identity_checks(root: Path, backend: str) -> list[dict[str, object]]:
+    """Agent-identity invariants (prompt-file-present, backend-consistency, skills)."""
+    checks: list[dict[str, object]] = []
+
+    expected = _PROMPT_FILE.get(backend)
+    if expected is None:
+        checks.append(
+            {
+                "id": "backend_consistency",
+                "passed": False,
+                "severity": "error",
+                "message": f"unknown backend '{backend}' in culture.yaml",
+                "remediation": f"set backend to one of: {', '.join(sorted(_PROMPT_FILE))}",
+            }
+        )
+    else:
+        present = (root / expected).is_file()
+        checks.append(
+            {
+                "id": "prompt_file_present",
+                "passed": present,
+                "severity": "error",
+                "message": (
+                    f"backend '{backend}' requires {expected} — "
+                    + ("present" if present else "missing")
+                ),
+                "remediation": "" if present else f"create {expected} at the repo root",
+            }
+        )
+
+    skills_dir = root / ".claude" / "skills"
+    has_skills = skills_dir.is_dir() and any(skills_dir.iterdir())
+    checks.append(
+        {
+            "id": "skills_present",
+            "passed": has_skills,
+            "severity": "warning",
+            "message": (
+                ".claude/skills/ vendored" if has_skills else ".claude/skills/ missing or empty"
+            ),
+            "remediation": (
+                "" if has_skills else "vendor the skill kit (see docs/skill-sources.md)"
+            ),
+        }
+    )
+    return checks
+
+
+def _qodo_setup_checks(repo_root: Path, home: Path) -> list[dict[str, object]]:
+    """Detect the Qodo configs a repo using qodo-cli should carry.
+
+    Advisory (``warning`` / ``info``): the remediation text guides an agent
+    through creating each one. None of these flip ``healthy``.
+    """
+    checks: list[dict[str, object]] = []
+
+    pr_agent = (repo_root / ".pr_agent.toml").is_file()
+    checks.append(
+        {
+            "id": "pr_agent_config_present",
+            "passed": pr_agent,
+            "severity": "warning",
+            "message": (
+                ".pr_agent.toml present (Qodo reviewer config)"
+                if pr_agent
+                else "no .pr_agent.toml — Qodo reviews this repo using only inferred conventions"
+            ),
+            "remediation": (
+                ""
+                if pr_agent
+                else (
+                    "add a minimal .pr_agent.toml with a [pr_reviewer] section "
+                    "(extra_instructions) describing this repo's intentional patterns. "
+                    f"Docs: {_CONFIG_DOCS}"
+                )
+            ),
+        }
+    )
+
+    best_practices = (repo_root / "best_practices.md").is_file()
+    checks.append(
+        {
+            "id": "best_practices_present",
+            "passed": best_practices,
+            "severity": "warning",
+            "message": (
+                "best_practices.md present"
+                if best_practices
+                else "no best_practices.md — Qodo won't flag this repo's best-practice violations"
+            ),
+            "remediation": (
+                ""
+                if best_practices
+                else (
+                    "add best_practices.md at the repo root listing this repo's coding "
+                    f"standards (auto-referenced by the reviewer). Docs: {_BEST_PRACTICES_DOCS}"
+                )
+            ),
+        }
+    )
+
+    ok, message, remediation = _client_credential_status(home)
+    checks.append(
+        {
+            "id": "qodo_client_config_present",
+            "passed": ok,
+            "severity": "info",
+            "message": message,
+            "remediation": remediation,
+        }
+    )
+    return checks
+
+
+def _client_credential_status(home: Path) -> tuple[bool, str, str]:
+    """Whether 'qodo rules' would find a usable API key — never raises.
+
+    Mirrors what the rules client actually needs (``qodo/cli/_qodo_api.py``):
+    a resolvable ``API_KEY`` from ``QODO_API_KEY`` or a readable, well-formed
+    ``~/.qodo/config.json``. Mere file existence is not enough. Returns
+    ``(passed, message, remediation)``.
+    """
+    if os.environ.get("QODO_API_KEY"):
+        return True, "Qodo API key available via QODO_API_KEY (for 'qodo rules')", ""
+
+    cfg_path = home / ".qodo" / "config.json"
+    if not cfg_path.is_file():
+        return (
+            False,
+            "no ~/.qodo/config.json and QODO_API_KEY unset (needed for 'qodo rules')",
+            'create ~/.qodo/config.json with an "API_KEY" (or export QODO_API_KEY). '
+            "Only 'qodo rules' needs it; 'qodo review' uses your provider-CLI auth.",
+        )
+    try:
+        data = json.loads(cfg_path.read_text(encoding="utf-8"))
+    except OSError:
+        return (
+            False,
+            "~/.qodo/config.json is present but unreadable",
+            "check the permissions on ~/.qodo/config.json",
+        )
+    except json.JSONDecodeError:
+        return (
+            False,
+            "~/.qodo/config.json is not valid JSON",
+            'repair ~/.qodo/config.json (it must be a JSON object with an "API_KEY")',
+        )
+    if not isinstance(data, dict) or not str(data.get("API_KEY") or "").strip():
+        return (
+            False,
+            "~/.qodo/config.json has no API_KEY (needed for 'qodo rules')",
+            'add a non-empty "API_KEY" to ~/.qodo/config.json (or export QODO_API_KEY)',
+        )
+    return True, "Qodo API key present in ~/.qodo/config.json (for 'qodo rules')", ""
+
+
+def _repo_root(start: Path) -> Path:
+    """The git repo root at/above ``start`` (where Qodo reads its config), or ``start``."""
+    for candidate in [start, *start.parents]:
+        if (candidate / ".git").exists():
+            return candidate
+    return start
+
+
+def _is_healthy(checks: list[dict[str, object]]) -> bool:
+    """Healthy iff every error-severity check passed (advisory checks never fail)."""
+    return all(c["passed"] for c in checks if c["severity"] == "error")
+
+
+def _diagnose() -> dict[str, object]:
+    checks: list[dict[str, object]] = []
+
+    cfg = find_culture_yaml()
+    if cfg is not None:
+        checks.extend(_identity_checks(cfg.parent, str(read_agent_fields()["backend"])))
+    else:
+        checks.append(
+            {
+                "id": "source_checkout",
+                "passed": True,
+                "severity": "info",
+                "message": "no culture.yaml alongside the package; agent-identity checks skipped",
+                "remediation": "",
+            }
+        )
+
+    checks.extend(_qodo_setup_checks(_repo_root(Path.cwd()), Path.home()))
+
+    return {"healthy": _is_healthy(checks), "checks": checks}
+
+
+def _mark(check: dict[str, object]) -> str:
+    if check["passed"]:
+        return "ok"
+    return {"error": "FAIL", "warning": "WARN"}.get(str(check["severity"]), "note")
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    report = _diagnose()
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(report, json_mode=True)
+    else:
+        status = "healthy" if report["healthy"] else "unhealthy"
+        lines = [f"qodo-cli doctor: {status}", ""]
+        for check in report["checks"]:  # type: ignore[attr-defined]
+            lines.append(f"[{_mark(check)}] {check['id']}: {check['message']}")
+            if not check["passed"] and check["remediation"]:
+                lines.append(f"  hint: {check['remediation']}")
+        emit_result("\n".join(lines), json_mode=False)
+    return 0 if report["healthy"] else 1
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "doctor",
+        help="Check agent-identity invariants and Qodo setup (configs); guides any fixes.",
+    )
+    add_json_flag(p)
+    p.set_defaults(func=cmd_doctor)

{qodo_cli-0.4.0 → qodo_cli-0.5.0}/qodo/cli/_commands/learn.py

@@ -34,7 +34,7 @@ Commands
   qodo-cli learn                This self-teaching prompt.
   qodo-cli explain <path>...    Markdown docs for any noun/verb path.
   qodo-cli overview             Descriptive snapshot of the agent.
-  qodo-cli doctor               Check the agent-identity invariants.
+  qodo-cli doctor               Check agent-identity invariants + Qodo setup.
   qodo-cli cli overview         Describe the CLI surface itself.
 
 Machine-readable output
@@ -69,7 +69,7 @@ def _as_json_payload() -> dict[str, object]:
             {"path": ["learn"], "summary": "Self-teaching prompt."},
             {"path": ["explain"], "summary": "Markdown docs by path."},
             {"path": ["overview"], "summary": "Descriptive snapshot of the agent."},
-            {"path": ["doctor"], "summary": "Check the agent-identity invariants."},
+            {"path": ["doctor"], "summary": "Check agent-identity invariants + Qodo setup."},
             {"path": ["cli", "overview"], "summary": "Describe the CLI surface."},
         ],
         "exit_codes": {

{qodo_cli-0.4.0 → qodo_cli-0.5.0}/qodo/cli/_commands/overview.py

@@ -32,7 +32,7 @@ _VERBS = [
     "learn — structured self-teaching prompt",
     "explain <path> — markdown docs for a topic",
     "overview — this descriptive snapshot",
-    "doctor — check the agent-identity invariants",
+    "doctor — check agent-identity invariants + Qodo setup (configs), with fix guidance",
 ]
 
 

{qodo_cli-0.4.0 → qodo_cli-0.5.0}/qodo/explain/catalog.py

@@ -156,9 +156,21 @@ ignored `target` so a stray path never hard-fails.
 _DOCTOR = """\
 # qodo-cli doctor
 
-Checks the agent-identity invariants `steward doctor` verifies:
-prompt-file-present and backend-consistency (`claude` → `CLAUDE.md`), plus a
-skills-present check. Exits 1 when unhealthy.
+Two groups of checks, emitted as
+`{healthy, checks: [{id, passed, severity, message, remediation}]}`:
+
+- **agent identity** (in a source checkout) — prompt-file-present and
+  backend-consistency, mirroring `steward doctor` (this repo's backend is
+  `colleague` → `AGENTS.colleague.md`), plus a `.claude/skills/` check.
+- **Qodo setup** (any repo, against the current git root) — whether
+  `.pr_agent.toml` and `best_practices.md` are present (tune Qodo's PR reviews)
+  and whether `~/.qodo/config.json` / `QODO_API_KEY` is available (for
+  `qodo rules`). These are advisory; each carries a `remediation` that guides
+  setup.
+
+`healthy` is true when every **error**-severity check passes; advisory
+(`warning`/`info`) checks surface guidance without flipping it. Exits 1 only on
+an error-severity failure.
 
 ## Usage
 

qodo_cli-0.5.0/tests/test_cli_introspection.py

@@ -0,0 +1,197 @@
+"""Tests for the introspection verbs: overview, cli overview, doctor."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from qodo.cli import main
+from qodo.cli._commands import doctor as _doctor
+
+# --- overview -------------------------------------------------------------
+
+
+def test_overview_text(capsys: pytest.CaptureFixture[str]) -> None:
+    rc = main(["overview"])
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "# qodo-cli" in out
+    assert "Identity" in out
+
+
+def test_overview_json_shape(capsys: pytest.CaptureFixture[str]) -> None:
+    rc = main(["overview", "--json"])
+    assert rc == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["subject"] == "qodo-cli"
+    assert isinstance(payload["sections"], list)
+    assert payload["sections"]
+
+
+def test_overview_graceful_on_bad_path(capsys: pytest.CaptureFixture[str]) -> None:
+    # Rubric contract: descriptive verbs never hard-fail on a missing target.
+    rc = main(["overview", "/no/such/path/here"])
+    assert rc == 0
+    assert capsys.readouterr().out.strip()
+
+
+# --- cli overview ---------------------------------------------------------
+
+
+def test_cli_overview_text(capsys: pytest.CaptureFixture[str]) -> None:
+    rc = main(["cli", "overview"])
+    assert rc == 0
+    assert "# qodo-cli cli" in capsys.readouterr().out
+
+
+def test_cli_overview_json_shape(capsys: pytest.CaptureFixture[str]) -> None:
+    rc = main(["cli", "overview", "--json"])
+    assert rc == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["subject"] == "qodo-cli cli"
+    assert isinstance(payload["sections"], list)
+
+
+def test_cli_noun_bare_is_non_empty(capsys: pytest.CaptureFixture[str]) -> None:
+    rc = main(["cli"])
+    assert rc == 0
+    assert capsys.readouterr().out.strip()
+
+
+def test_cli_overview_unknown_flag_structured_error(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    # `cli overview` parse errors must route through the structured error
+    # contract (error:/hint: + exit 1), not argparse's default stderr/exit 2.
+    with pytest.raises(SystemExit) as exc:
+        main(["cli", "overview", "--bogus"])
+    assert exc.value.code == 1
+    err = capsys.readouterr().err
+    assert err.startswith("error:")
+    assert "hint:" in err
+
+
+# --- doctor ---------------------------------------------------------------
+
+
+def test_doctor_text(capsys: pytest.CaptureFixture[str]) -> None:
+    rc = main(["doctor"])
+    assert rc in (0, 1)
+    assert "qodo-cli doctor" in capsys.readouterr().out
+
+
+def test_doctor_json_shape(capsys: pytest.CaptureFixture[str]) -> None:
+    rc = main(["doctor", "--json"])
+    assert rc in (0, 1)
+    payload = json.loads(capsys.readouterr().out)
+    assert isinstance(payload["healthy"], bool)
+    assert isinstance(payload["checks"], list)
+    assert payload["checks"]
+    for check in payload["checks"]:
+        assert {"id", "passed", "severity", "message", "remediation"} <= set(check)
+
+
+def test_doctor_recognizes_declared_backend(capsys: pytest.CaptureFixture[str]) -> None:
+    """The repo's own declared backend must be a known one — doctor stays healthy.
+
+    Guards the backend-consistency invariant: a promotion that changes
+    ``culture.yaml``'s backend without teaching ``doctor`` the matching prompt
+    file would otherwise slip through (the shape tests above tolerate rc==1).
+    """
+    rc = main(["doctor", "--json"])
+    payload = json.loads(capsys.readouterr().out)
+    messages = " ".join(str(c["message"]) for c in payload["checks"])
+    assert "unknown backend" not in messages
+    assert rc == 0
+    assert payload["healthy"] is True
+
+
+# --- doctor: Qodo-setup detection -----------------------------------------
+
+
+def test_doctor_reports_qodo_setup_checks(capsys: pytest.CaptureFixture[str]) -> None:
+    main(["doctor", "--json"])
+    payload = json.loads(capsys.readouterr().out)
+    ids = {c["id"] for c in payload["checks"]}
+    assert {
+        "pr_agent_config_present",
+        "best_practices_present",
+        "qodo_client_config_present",
+    } <= ids
+
+
+def test_qodo_setup_checks_flag_missing(tmp_path) -> None:
+    # Empty repo root + home with no ~/.qodo/config.json and no QODO_API_KEY.
+    home = tmp_path / "home"
+    home.mkdir()
+    import os
+    from unittest import mock
+
+    with mock.patch.dict(os.environ, {}, clear=False):
+        os.environ.pop("QODO_API_KEY", None)
+        checks = {c["id"]: c for c in _doctor._qodo_setup_checks(tmp_path, home)}
+    assert checks["pr_agent_config_present"]["passed"] is False
+    assert checks["best_practices_present"]["passed"] is False
+    assert checks["qodo_client_config_present"]["passed"] is False
+    # Advisory only — none is error-severity, and each guides setup.
+    for c in checks.values():
+        assert c["severity"] in ("warning", "info")
+        assert c["remediation"]  # non-empty guidance
+
+
+def test_qodo_setup_checks_pass_when_present(tmp_path, monkeypatch: pytest.MonkeyPatch) -> None:
+    (tmp_path / ".pr_agent.toml").write_text("[pr_reviewer]\n", encoding="utf-8")
+    (tmp_path / "best_practices.md").write_text("# bp\n", encoding="utf-8")
+    home = tmp_path / "home"
+    (home / ".qodo").mkdir(parents=True)
+    # A real API_KEY — not just an existing file (that was the bug Qodo caught).
+    (home / ".qodo" / "config.json").write_text('{"API_KEY": "k"}', encoding="utf-8")
+    monkeypatch.delenv("QODO_API_KEY", raising=False)
+    checks = {c["id"]: c for c in _doctor._qodo_setup_checks(tmp_path, home)}
+    assert all(checks[k]["passed"] for k in checks)
+
+
+def test_qodo_client_config_fails_without_api_key(
+    tmp_path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # An existing config.json with no API_KEY must NOT pass — `qodo rules` needs the key.
+    home = tmp_path / "home"
+    (home / ".qodo").mkdir(parents=True)
+    (home / ".qodo" / "config.json").write_text("{}", encoding="utf-8")
+    monkeypatch.delenv("QODO_API_KEY", raising=False)
+    checks = {c["id"]: c for c in _doctor._qodo_setup_checks(tmp_path, home)}
+    cc = checks["qodo_client_config_present"]
+    assert cc["passed"] is False
+    assert cc["remediation"]
+
+
+def test_qodo_client_config_malformed_does_not_throw(
+    tmp_path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    home = tmp_path / "home"
+    (home / ".qodo").mkdir(parents=True)
+    (home / ".qodo" / "config.json").write_text("{not json", encoding="utf-8")
+    monkeypatch.delenv("QODO_API_KEY", raising=False)
+    # Must not raise; reports a failed advisory check with guidance.
+    checks = {c["id"]: c for c in _doctor._qodo_setup_checks(tmp_path, home)}
+    cc = checks["qodo_client_config_present"]
+    assert cc["passed"] is False
+    assert "JSON" in cc["message"] or "valid" in cc["message"]
+
+
+def test_qodo_client_config_satisfied_by_env(tmp_path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("QODO_API_KEY", "k")
+    checks = {c["id"]: c for c in _doctor._qodo_setup_checks(tmp_path, tmp_path)}
+    assert checks["qodo_client_config_present"]["passed"] is True
+
+
+def test_is_healthy_ignores_advisory_failures() -> None:
+    checks = [
+        {"id": "a", "passed": True, "severity": "error"},
+        {"id": "b", "passed": False, "severity": "warning"},
+        {"id": "c", "passed": False, "severity": "info"},
+    ]
+    assert _doctor._is_healthy(checks) is True
+    checks.append({"id": "d", "passed": False, "severity": "error"})
+    assert _doctor._is_healthy(checks) is False

{qodo_cli-0.4.0 → qodo_cli-0.5.0}/uv.lock

@@ -417,7 +417,7 @@ wheels = [
 
 [[package]]
 name = "qodo-cli"
-version = "0.4.0"
+version = "0.5.0"
 source = { editable = "." }
 
 [package.dev-dependencies]

qodo_cli-0.4.0/qodo/cli/_commands/doctor.py

@@ -1,124 +0,0 @@
-"""``qodo-cli doctor`` — check the agent-identity invariants.
-
-Mirrors the two invariants ``steward doctor`` verifies for a mesh agent:
-
-* **prompt-file-present** — the repo declares an agent in ``culture.yaml`` and
-  has the matching prompt file on disk;
-* **backend-consistency** — the declared ``backend`` matches the prompt file
-  (``claude`` → ``CLAUDE.md``, ``colleague`` → ``AGENTS.colleague.md``,
-  ``acp`` → ``AGENTS.md``, ``gemini`` → ``GEMINI.md``).
-
-Plus a **skills-present** check (the vendored ``.claude/skills/`` kit). Read-only.
-
-Reports the rubric-shaped contract
-``{healthy, checks: [{id, passed, severity, message, remediation}]}`` so the
-agent-first rubric's bundle 7 passes. When run from a wheel install (no
-``culture.yaml`` alongside the package), it reports a single info check and
-exits 0 — there is nothing to diagnose.
-"""
-
-from __future__ import annotations
-
-import argparse
-
-from qodo.cli._commands.whoami import find_culture_yaml, read_agent_fields
-from qodo.cli._output import add_json_flag, emit_result
-
-# backend → required prompt file (the backend-consistency mapping).
-_PROMPT_FILE = {
-    "claude": "CLAUDE.md",
-    "colleague": "AGENTS.colleague.md",
-    "acp": "AGENTS.md",
-    "gemini": "GEMINI.md",
-}
-
-
-def _diagnose() -> dict[str, object]:
-    cfg = find_culture_yaml()
-    if cfg is None:
-        check = {
-            "id": "source_checkout",
-            "passed": True,
-            "severity": "info",
-            "message": "no culture.yaml found alongside the package; identity checks skipped",
-            "remediation": "",
-        }
-        return {"healthy": True, "checks": [check]}
-
-    root = cfg.parent
-    fields = read_agent_fields()
-    backend = fields["backend"]
-    checks: list[dict[str, object]] = []
-
-    # 1. backend-consistency: the prompt file for the declared backend exists.
-    expected = _PROMPT_FILE.get(backend)
-    if expected is None:
-        checks.append(
-            {
-                "id": "backend_consistency",
-                "passed": False,
-                "severity": "error",
-                "message": f"unknown backend '{backend}' in culture.yaml",
-                "remediation": f"set backend to one of: {', '.join(sorted(_PROMPT_FILE))}",
-            }
-        )
-    else:
-        present = (root / expected).is_file()
-        checks.append(
-            {
-                "id": "prompt_file_present",
-                "passed": present,
-                "severity": "error",
-                "message": (
-                    f"backend '{backend}' requires {expected} — "
-                    + ("present" if present else "missing")
-                ),
-                "remediation": "" if present else f"create {expected} at the repo root",
-            }
-        )
-
-    # 2. skills-present: the vendored skill kit is on disk.
-    skills_dir = root / ".claude" / "skills"
-    has_skills = skills_dir.is_dir() and any(skills_dir.iterdir())
-    checks.append(
-        {
-            "id": "skills_present",
-            "passed": has_skills,
-            "severity": "warning",
-            "message": (
-                ".claude/skills/ vendored" if has_skills else ".claude/skills/ missing or empty"
-            ),
-            "remediation": (
-                "" if has_skills else "vendor the skill kit (see docs/skill-sources.md)"
-            ),
-        }
-    )
-
-    healthy = all(c["passed"] for c in checks)
-    return {"healthy": healthy, "checks": checks}
-
-
-def cmd_doctor(args: argparse.Namespace) -> int:
-    report = _diagnose()
-    json_mode = bool(getattr(args, "json", False))
-    if json_mode:
-        emit_result(report, json_mode=True)
-    else:
-        status = "healthy" if report["healthy"] else "unhealthy"
-        lines = [f"qodo-cli doctor: {status}", ""]
-        for check in report["checks"]:
-            mark = "ok" if check["passed"] else "FAIL"
-            lines.append(f"[{mark}] {check['id']}: {check['message']}")
-            if not check["passed"] and check["remediation"]:
-                lines.append(f"  hint: {check['remediation']}")
-        emit_result("\n".join(lines), json_mode=False)
-    return 0 if report["healthy"] else 1
-
-
-def register(sub: argparse._SubParsersAction) -> None:
-    p = sub.add_parser(
-        "doctor",
-        help="Check the agent-identity invariants (prompt-file-present, backend-consistency).",
-    )
-    add_json_flag(p)
-    p.set_defaults(func=cmd_doctor)

qodo_cli-0.4.0/tests/test_cli_introspection.py

@@ -1,106 +0,0 @@
-"""Tests for the introspection verbs: overview, cli overview, doctor."""
-
-from __future__ import annotations
-
-import json
-
-import pytest
-
-from qodo.cli import main
-
-# --- overview -------------------------------------------------------------
-
-
-def test_overview_text(capsys: pytest.CaptureFixture[str]) -> None:
-    rc = main(["overview"])
-    assert rc == 0
-    out = capsys.readouterr().out
-    assert "# qodo-cli" in out
-    assert "Identity" in out
-
-
-def test_overview_json_shape(capsys: pytest.CaptureFixture[str]) -> None:
-    rc = main(["overview", "--json"])
-    assert rc == 0
-    payload = json.loads(capsys.readouterr().out)
-    assert payload["subject"] == "qodo-cli"
-    assert isinstance(payload["sections"], list)
-    assert payload["sections"]
-
-
-def test_overview_graceful_on_bad_path(capsys: pytest.CaptureFixture[str]) -> None:
-    # Rubric contract: descriptive verbs never hard-fail on a missing target.
-    rc = main(["overview", "/no/such/path/here"])
-    assert rc == 0
-    assert capsys.readouterr().out.strip()
-
-
-# --- cli overview ---------------------------------------------------------
-
-
-def test_cli_overview_text(capsys: pytest.CaptureFixture[str]) -> None:
-    rc = main(["cli", "overview"])
-    assert rc == 0
-    assert "# qodo-cli cli" in capsys.readouterr().out
-
-
-def test_cli_overview_json_shape(capsys: pytest.CaptureFixture[str]) -> None:
-    rc = main(["cli", "overview", "--json"])
-    assert rc == 0
-    payload = json.loads(capsys.readouterr().out)
-    assert payload["subject"] == "qodo-cli cli"
-    assert isinstance(payload["sections"], list)
-
-
-def test_cli_noun_bare_is_non_empty(capsys: pytest.CaptureFixture[str]) -> None:
-    rc = main(["cli"])
-    assert rc == 0
-    assert capsys.readouterr().out.strip()
-
-
-def test_cli_overview_unknown_flag_structured_error(
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    # `cli overview` parse errors must route through the structured error
-    # contract (error:/hint: + exit 1), not argparse's default stderr/exit 2.
-    with pytest.raises(SystemExit) as exc:
-        main(["cli", "overview", "--bogus"])
-    assert exc.value.code == 1
-    err = capsys.readouterr().err
-    assert err.startswith("error:")
-    assert "hint:" in err
-
-
-# --- doctor ---------------------------------------------------------------
-
-
-def test_doctor_text(capsys: pytest.CaptureFixture[str]) -> None:
-    rc = main(["doctor"])
-    assert rc in (0, 1)
-    assert "qodo-cli doctor" in capsys.readouterr().out
-
-
-def test_doctor_json_shape(capsys: pytest.CaptureFixture[str]) -> None:
-    rc = main(["doctor", "--json"])
-    assert rc in (0, 1)
-    payload = json.loads(capsys.readouterr().out)
-    assert isinstance(payload["healthy"], bool)
-    assert isinstance(payload["checks"], list)
-    assert payload["checks"]
-    for check in payload["checks"]:
-        assert {"id", "passed", "severity", "message", "remediation"} <= set(check)
-
-
-def test_doctor_recognizes_declared_backend(capsys: pytest.CaptureFixture[str]) -> None:
-    """The repo's own declared backend must be a known one — doctor stays healthy.
-
-    Guards the backend-consistency invariant: a promotion that changes
-    ``culture.yaml``'s backend without teaching ``doctor`` the matching prompt
-    file would otherwise slip through (the shape tests above tolerate rc==1).
-    """
-    rc = main(["doctor", "--json"])
-    payload = json.loads(capsys.readouterr().out)
-    messages = " ".join(str(c["message"]) for c in payload["checks"])
-    assert "unknown backend" not in messages
-    assert rc == 0
-    assert payload["healthy"] is True