cendor-init 0.1.0__py3-none-any.whl

cendor_init/__init__.py

@@ -0,0 +1,15 @@
+"""cendor-init — offline CLI to wire Cendor + your AI assistant (``init``) and validate the wiring
+(``doctor``). Optional developer tooling; no Cendor library depends on it, and it makes no network
+call. See https://cendor.ai/docs/for-ai-assistants.
+
+This is a standalone top-level package (``cendor_init``) — NOT part of the PEP 420 ``cendor.*``
+namespace — mirroring how ``cendor-mcp`` ships ``cendor_mcp``.
+"""
+
+from __future__ import annotations
+
+from .doctor import run_doctor
+from .initialize import run_init
+
+__all__ = ["run_init", "run_doctor", "__version__"]
+__version__ = "0.1.0"

cendor_init/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m cendor_init`` in addition to the ``cendor-init`` console script / ``uvx``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cendor_init/cli.py

@@ -0,0 +1,188 @@
+"""``cendor-init`` — one command to make a project Cendor-ready and Cendor-fluent for its AI
+assistant, plus a ``doctor`` that catches wiring mistakes before they bite. Offline: no network, no key.
+
+    uvx cendor-init            # detect + write assistant rules (idempotent)
+    uvx cendor-init doctor     # validate wiring; non-zero exit on hard problems (CI-usable)
+
+See https://cendor.ai/docs/for-ai-assistants and https://cendor.ai/mcp.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import textwrap
+from pathlib import Path
+
+from .doctor import SEVERITY_RANK, Finding, run_doctor
+from .initialize import ALL_ASSISTANTS, InitOptions, run_init
+
+__all__ = ["main"]
+
+_ICON = {
+    "created": "+",
+    "updated": "~",
+    "appended": "~",
+    "skipped": "·",
+    "would-create": "+",
+    "would-update": "~",
+    "would-append": "~",
+    "would-skip": "·",
+}
+
+
+def _version() -> str:
+    try:
+        from importlib import metadata
+
+        return metadata.version("cendor-init")
+    except Exception:
+        return "0.1.0"
+
+
+def _parse_assistants(raw: list[str] | None) -> list[str] | None:
+    if not raw:
+        return None
+    wanted: list[str] = []
+    for item in raw:
+        for part in item.split(","):
+            part = part.strip().lower()
+            if part and part not in wanted:
+                wanted.append(part)
+    bad = [w for w in wanted if w not in ALL_ASSISTANTS]
+    if bad:
+        sys.stderr.write(f"cendor-init: unknown assistant(s): {', '.join(bad)}\n")
+        sys.stderr.write(f"             valid: {', '.join(ALL_ASSISTANTS)}\n")
+        raise SystemExit(2)
+    return wanted
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    root = Path.cwd()
+    opts = InitOptions(
+        root=root,
+        assistants=_parse_assistants(args.assistant),
+        all=args.all,
+        mcp=args.mcp,
+        scaffold=args.scaffold,
+        force=args.force,
+        dry_run=args.dry_run,
+    )
+    result = run_init(opts)
+    dry = opts.dry_run
+    eco = result.detected.ecosystem
+
+    out = sys.stdout.write
+    out(
+        f"\ncendor-init — {'dry run (no files written)' if dry else 'wiring Cendor for your assistant'}\n"
+    )
+    line = "no package.json / pyproject found" if eco == "unknown" else f"{eco} project"
+    if result.detected.declared_providers:
+        line += f"  ·  providers: {', '.join(sorted(result.detected.declared_providers))}"
+    out(f"project: {line}\n\n")
+
+    for a in result.actions:
+        icon = _ICON.get(a.status, "·")
+        note = f"  ({a.note})" if a.note else ""
+        out(f"  {icon} {a.status:<13} {a.path}{note}\n")
+
+    out("\nMCP (agent-mode assistants):\n")
+    for ln in result.mcp_guidance.split("\n"):
+        out(f"  {ln}\n")
+
+    out("\nNext:\n")
+    out("  • Trust your editor's hover/completion — every Cendor symbol ships an @example.\n")
+    out("  • Full trap sheet:  https://cendor.ai/docs/for-ai-assistants\n")
+    out("  • Validate wiring:  uvx cendor-init doctor\n\n")
+    return 0
+
+
+def _print_finding(f: Finding) -> None:
+    tag = {"error": "ERROR", "warn": "WARN ", "ok": "OK   "}.get(f.severity, "INFO ")
+    out = sys.stdout.write
+    out(f"  [{tag}] {f.title}\n")
+    for ln in textwrap.wrap(f.detail, width=88):
+        out(f"          {ln}\n")
+    if f.fix:
+        out(f"          fix: {f.fix}\n")
+    for loc in f.locations:
+        out(f"          - {loc}\n")
+    out("\n")
+
+
+def _cmd_doctor(_args: argparse.Namespace) -> int:
+    result = run_doctor(Path.cwd())
+    sys.stdout.write("\ncendor-init doctor\n\n")
+    for f in sorted(result.findings, key=lambda x: SEVERITY_RANK.get(x.severity, 9)):
+        _print_finding(f)
+    errors = sum(1 for f in result.findings if f.severity == "error")
+    warns = sum(1 for f in result.findings if f.severity == "warn")
+    tail = "OK." if result.exit_code == 0 else "Fix the errors above."
+    sys.stdout.write(f"{errors} error(s), {warns} warning(s). {tail}\n\n")
+    return result.exit_code
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cendor-init",
+        description="Wire Cendor + your AI assistant, offline.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="Docs: https://cendor.ai/docs/for-ai-assistants   MCP: https://cendor.ai/mcp",
+    )
+    parser.add_argument("-v", "--version", action="version", version=_version())
+    sub = parser.add_subparsers(dest="command")
+
+    p_init = sub.add_parser("init", help="write assistant rules files (default command)")
+    _add_init_args(p_init)
+    sub.add_parser("doctor", help="validate the wiring (never writes); exit 1 on hard problems")
+    return parser
+
+
+def _add_init_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--all", action="store_true", help="write every assistant rules file")
+    p.add_argument(
+        "--assistant",
+        action="append",
+        metavar="LIST",
+        help="comma-separated subset: copilot,cursor,agents,claude,windsurf",
+    )
+    p.add_argument("--mcp", action="store_true", help="also drop MCP connect config where absent")
+    p.add_argument(
+        "--scaffold", action="store_true", help="also write a correct instrument()+budget starter"
+    )
+    p.add_argument(
+        "--force", action="store_true", help="overwrite an owned file (.cursor/rules/cendor.mdc)"
+    )
+    p.add_argument("--dry-run", action="store_true", help="show what would change without writing")
+    p.add_argument("-y", "--yes", action="store_true", help=argparse.SUPPRESS)
+
+
+def _force_utf8() -> None:
+    """Our output uses em-dashes / bullets. A Windows console defaults to a non-UTF-8 code page,
+    which would raise UnicodeEncodeError on those — force UTF-8 (with a replace fallback)."""
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(encoding="utf-8", errors="replace")
+            except (ValueError, OSError):  # pragma: no cover - stream doesn't support it
+                pass
+
+
+def main(argv: list[str] | None = None) -> int:
+    _force_utf8()
+    argv = list(sys.argv[1:] if argv is None else argv)
+    # Default to `init` when no subcommand is given (mirrors `npx @cendor/init`).
+    if not argv or (argv[0].startswith("-") and argv[0] not in ("-h", "--help", "-v", "--version")):
+        argv = ["init", *argv]
+
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    command = args.command or "init"
+    if command == "doctor":
+        return _cmd_doctor(args)
+    return _cmd_init(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

cendor_init/detect.py

@@ -0,0 +1,226 @@
+"""Detect the project shape, which assistants are configured, which providers / cendor packages exist."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from importlib import metadata
+from pathlib import Path
+
+# PyPI provider distribution / import token -> normalized provider key.
+PYPI_PROVIDERS: dict[str, str] = {
+    "openai": "openai",
+    "anthropic": "anthropic",
+    "google-genai": "google",
+    "google-generativeai": "google",
+    "google.genai": "google",
+    "google_genai": "google",
+    "boto3": "bedrock",
+    "ollama": "ollama",
+    "mistralai": "mistral",
+    "cohere": "cohere",
+    "huggingface_hub": "huggingface",
+    "huggingface-hub": "huggingface",
+}
+
+# npm provider package -> normalized provider key (for the cross-ecosystem "used in .ts source" note).
+NPM_PROVIDERS: dict[str, str] = {
+    "openai": "openai",
+    "@anthropic-ai/sdk": "anthropic",
+    "@google/genai": "google",
+    "@google/generative-ai": "google",
+    "@aws-sdk/client-bedrock-runtime": "bedrock",
+    "ollama": "ollama",
+    "@mistralai/mistralai": "mistral",
+    "cohere-ai": "cohere",
+}
+
+# The PyPI distribution that ships each provider SDK (for the "install X" fix hint).
+PYPI_PKG_FOR_PROVIDER: dict[str, str] = {
+    "openai": "openai",
+    "anthropic": "anthropic",
+    "google": "google-genai",
+    "bedrock": "boto3",
+    "ollama": "ollama",
+    "mistral": "mistralai",
+    "cohere": "cohere",
+    "huggingface": "huggingface_hub",
+}
+
+# The cendor-sdk extra that pulls each provider (nicer fix hint than the bare package).
+SDK_EXTRA_FOR_PROVIDER: dict[str, str] = {
+    "openai": "openai",
+    "anthropic": "anthropic",
+    "google": "google",
+    "bedrock": "bedrock",
+    "ollama": "ollama",
+    "huggingface": "huggingface",
+}
+
+CENDOR_DISTS = list(
+    {
+        "cendor-core",
+        "cendor-tokenguard",
+        "cendor-guardrails",
+        "cendor-contextkit",
+        "cendor-squeeze",
+        "cendor-cassette",
+        "cendor-acttrace",
+        "cendor-libs",
+        "cendor",
+        "cendor-sdk",
+    }
+)
+
+_PY_IMPORT_RE = re.compile(
+    r"(?:^|\n)[ \t]*(?:import|from)[ \t]+"
+    r"(openai|anthropic|google\.genai|google_genai|boto3|ollama|mistralai|cohere|huggingface_hub)\b"
+)
+_NPM_IMPORT_RE = re.compile(
+    r"""(?:from|require|import)\s*\(?\s*['"]"""
+    r"(openai|@anthropic-ai/sdk|@google/genai|@google/generative-ai|"
+    r"@aws-sdk/client-bedrock-runtime|ollama|@mistralai/mistralai|cohere-ai)['\"]"
+)
+# A dependency token like `cendor-core>=1.3,<2` or `openai` (quoted or bare) in pyproject/requirements.
+_DEP_RE = re.compile(r"""["'\s]([A-Za-z][A-Za-z0-9._-]*)\s*((?:[<>=!~]=?|==)\s*[0-9][^"',\]]*)?""")
+
+
+@dataclass
+class Detected:
+    root: Path
+    ecosystem: str  # "node" | "python" | "unknown"
+    node: bool
+    python: bool
+    declared_providers: set[str] = field(default_factory=set)
+    assistants: list[str] = field(default_factory=list)
+    # cendor-* -> version spec declared in pyproject/requirements.
+    declared_pypi: dict[str, str] = field(default_factory=dict)
+    # cendor-* -> installed version (importlib.metadata) if importable in THIS environment.
+    installed_pypi: dict[str, str] = field(default_factory=dict)
+    # @cendor/* -> range declared in package.json (cross-ecosystem hint).
+    declared_npm: dict[str, str] = field(default_factory=dict)
+
+
+def installed_version(dist: str) -> str | None:
+    try:
+        return metadata.version(dist)
+    except metadata.PackageNotFoundError:
+        return None
+    except Exception:  # pragma: no cover - defensive
+        return None
+
+
+def _parse_py_deps(text: str) -> tuple[dict[str, str], set[str]]:
+    cendor: dict[str, str] = {}
+    providers: set[str] = set()
+    for m in _DEP_RE.finditer(text):
+        raw = (m.group(1) or "").lower()
+        spec = re.sub(r"\s+", "", m.group(2) or "")
+        base = raw.split("[")[0]  # strip extras like cendor-sdk[all]
+        if base.startswith("cendor"):
+            cendor[base] = spec or "*"
+        if base in PYPI_PROVIDERS:
+            providers.add(PYPI_PROVIDERS[base])
+    return cendor, providers
+
+
+def _detect_assistants(root: Path) -> list[str]:
+    found: list[str] = []
+    if (root / ".github").exists():
+        found.append("copilot")
+    if (root / ".cursor").exists():
+        found.append("cursor")
+    if (root / "AGENTS.md").exists():
+        found.append("agents")
+    if (root / "CLAUDE.md").exists():
+        found.append("claude")
+    if (root / ".windsurf").exists():
+        found.append("windsurf")
+    return found
+
+
+def _pkg_deps(pkg: dict) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for key in ("dependencies", "devDependencies", "peerDependencies", "optionalDependencies"):
+        block = pkg.get(key)
+        if isinstance(block, dict):
+            out.update({str(k): str(v) for k, v in block.items()})
+    return out
+
+
+def detect_project(root: Path) -> Detected:
+    root = Path(root)
+    node = (root / "package.json").exists()
+    python = (
+        (root / "pyproject.toml").exists()
+        or (root / "setup.py").exists()
+        or (root / "setup.cfg").exists()
+        or any(
+            p.name.startswith("requirements") and p.suffix == ".txt"
+            for p in root.glob("requirements*.txt")
+        )
+    )
+    ecosystem = "node" if node else "python" if python else "unknown"
+
+    declared_providers: set[str] = set()
+    declared_pypi: dict[str, str] = {}
+    declared_npm: dict[str, str] = {}
+
+    if python:
+        for fname in ("pyproject.toml", "requirements.txt", "requirements-dev.txt", "setup.cfg"):
+            fpath = root / fname
+            if not fpath.exists():
+                continue
+            cendor, provs = _parse_py_deps(fpath.read_text(encoding="utf-8", errors="ignore"))
+            declared_pypi.update(cendor)
+            declared_providers |= provs
+
+    if node:
+        try:
+            pkg = json.loads((root / "package.json").read_text(encoding="utf-8", errors="ignore"))
+            for name, ver in _pkg_deps(pkg).items():
+                if name in NPM_PROVIDERS:
+                    declared_providers.add(NPM_PROVIDERS[name])
+                if name.startswith("@cendor/"):
+                    declared_npm[name] = ver
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    # Installed cendor versions from the CURRENT environment (accurate when installed into the
+    # project venv; empty under `uvx` isolation, where we fall back to the declared pins above).
+    installed_pypi = {d: v for d in CENDOR_DISTS if (v := installed_version(d)) is not None}
+
+    return Detected(
+        root=root,
+        ecosystem=ecosystem,
+        node=node,
+        python=python,
+        declared_providers=declared_providers,
+        assistants=_detect_assistants(root),
+        declared_pypi=declared_pypi,
+        installed_pypi=installed_pypi,
+        declared_npm=declared_npm,
+    )
+
+
+def providers_used_in_source(text: str, kind: str) -> set[str]:
+    used: set[str] = set()
+    if kind == "python":
+        for m in _PY_IMPORT_RE.finditer(text):
+            tok = m.group(1)
+            key = PYPI_PROVIDERS.get(tok) or PYPI_PROVIDERS.get(tok.replace(".", "_"))
+            if key:
+                used.add(key)
+    else:
+        for m in _NPM_IMPORT_RE.finditer(text):
+            key = NPM_PROVIDERS.get(m.group(1))
+            if key:
+                used.add(key)
+    return used
+
+
+def provider_installed(provider: str) -> bool:
+    """Is the provider SDK importable in THIS environment?"""
+    pkg = PYPI_PKG_FOR_PROVIDER.get(provider)
+    return bool(pkg and installed_version(pkg) is not None)

cendor_init/doctor.py

@@ -0,0 +1,259 @@
+"""``doctor`` — validate the wiring so it doesn't break at runtime. Static checks only; NEVER mutates.
+
+Exits non-zero on hard problems (CI-usable), zero when only warnings remain. Python is checked with
+the installed environment (importlib.metadata) when available — accurate — and falls back to the
+declared pins under ``uvx`` isolation. The npm ecosystem gets a "run @cendor/init doctor" pointer.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import versions as version_snapshot
+from .detect import (
+    PYPI_PKG_FOR_PROVIDER,
+    SDK_EXTRA_FOR_PROVIDER,
+    Detected,
+    detect_project,
+    provider_installed,
+    providers_used_in_source,
+)
+from .scan import rel, walk_source
+from .semver import clean_version, compare_versions, range_blocks_latest
+
+PY_EXTS = (".py",)
+NODE_EXTS = (".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs")
+
+_MONEY_CONTEXT = re.compile(r"(cost|price|prices|money|usd|\.estimate\s*\(|Money|Decimal)")
+_INSTRUMENT_RE = re.compile(r"\binstrument\s*\(")
+_USES_CENDOR_RE = re.compile(r"from\s+cendor[.\s]|import\s+cendor|@cendor/")
+_BARE_IMPORT_RE = re.compile(r"(?:^|\n)[ \t]*import[ \t]+cendor[ \t]*(?:#.*)?(?:\n|$)")
+_STRAY_INIT_RE = re.compile(r"(?:^|[\\/])cendor[\\/]__init__\.py$")
+
+
+@dataclass
+class Finding:
+    severity: str  # "error" | "warn" | "info" | "ok"
+    title: str
+    detail: str
+    fix: str | None = None
+    locations: list[str] = field(default_factory=list)
+
+
+@dataclass
+class DoctorResult:
+    findings: list[Finding]
+    exit_code: int
+
+
+@dataclass
+class _Src:
+    py: list[tuple[str, str]]  # (path, text)
+    node: list[tuple[str, str]]
+
+
+def _read_all(paths: list[Path]) -> list[tuple[str, str]]:
+    out: list[tuple[str, str]] = []
+    for p in paths:
+        try:
+            out.append((str(p), p.read_text(encoding="utf-8", errors="ignore")))
+        except OSError:
+            continue
+    return out
+
+
+def _index(root: Path) -> _Src:
+    return _Src(
+        py=_read_all(walk_source(root, PY_EXTS)), node=_read_all(walk_source(root, NODE_EXTS))
+    )
+
+
+def _usage(src: _Src) -> tuple[int, bool]:
+    count = 0
+    uses = False
+    for _, text in src.py + src.node:
+        count += len(_INSTRUMENT_RE.findall(text))
+        if _USES_CENDOR_RE.search(text):
+            uses = True
+    return count, uses
+
+
+def _check_stray_init(root: Path, src: _Src, out: list[Finding]) -> None:
+    stray = [rel(root, Path(p)) for p, _ in src.py if _STRAY_INIT_RE.search(p)]
+    if stray:
+        out.append(
+            Finding(
+                "error",
+                "A top-level cendor/__init__.py exists",
+                "`cendor` is a PEP 420 namespace package. A top-level `cendor/__init__.py` in your own "
+                "tree shadows the namespace and breaks every `from cendor.<tool> import ...`.",
+                "Delete the file. Each Cendor distribution owns only cendor/<tool>/, never cendor/__init__.py.",
+                stray,
+            )
+        )
+
+
+def _check_bare_import(root: Path, src: _Src, out: list[Finding]) -> None:
+    hits = [rel(root, Path(p)) for p, text in src.py if _BARE_IMPORT_RE.search(text)]
+    if hits:
+        out.append(
+            Finding(
+                "warn",
+                "Bare `import cendor`",
+                "`cendor` is a namespace with no module body, so `import cendor` imports nothing usable.",
+                "Import from the flat path instead, e.g. `from cendor.tokenguard import budget`.",
+                hits[:8],
+            )
+        )
+
+
+def _check_instrument(count: int, uses: bool, out: list[Finding]) -> None:
+    if uses and count == 0:
+        out.append(
+            Finding(
+                "warn",
+                "No instrument() call found",
+                "Cendor is imported but the provider client is never wrapped, so nothing is observed — "
+                "budgets, gating, and audit will all see zero calls.",
+                "Wrap the client once: `client = instrument(OpenAI())`.",
+            )
+        )
+
+
+def _check_money(root: Path, src: _Src, out: list[Finding]) -> None:
+    hits: list[str] = []
+    for p, text in src.py:
+        for line in text.splitlines():
+            if re.search(r"\bfloat\s*\(", line) and _MONEY_CONTEXT.search(line):
+                hits.append(rel(root, Path(p)))
+                break
+    for p, text in src.node:
+        for line in text.splitlines():
+            if (
+                re.search(r"\bNumber\s*\(", line) or ".toNumber()" in line
+            ) and _MONEY_CONTEXT.search(line):
+                hits.append(rel(root, Path(p)))
+                break
+    if hits:
+        out.append(
+            Finding(
+                "warn",
+                "Money coerced to a float / number",
+                "Cost and price values are Decimal / decimal.js on purpose — converting to float/number "
+                "reintroduces the rounding error the Decimal type exists to prevent.",
+                "Keep money as Decimal; format only at the edge with str().",
+                sorted(set(hits))[:8],
+            )
+        )
+
+
+def _check_py_providers(detected: Detected, src: _Src, out: list[Finding]) -> None:
+    used: set[str] = set()
+    for _, text in src.py:
+        used |= providers_used_in_source(text, "python")
+    for p in sorted(used):
+        present = p in detected.declared_providers or provider_installed(p)
+        if present:
+            continue
+        pkg = PYPI_PKG_FOR_PROVIDER.get(p, p)
+        extra = SDK_EXTRA_FOR_PROVIDER.get(p)
+        fix = (
+            f'pip install "cendor-sdk[{extra}]"  (or `pip install {pkg}`)'
+            if extra
+            else f"pip install {pkg}"
+        )
+        out.append(
+            Finding(
+                "error",
+                f'Provider SDK for "{p}" is used but not installed',
+                f"Your code imports the {p} SDK, but it is neither declared in pyproject/requirements "
+                "nor importable here. Cendor never pulls a provider SDK for you — it is an optional extra.",
+                fix,
+            )
+        )
+
+
+def _check_py_versions(detected: Detected, out: list[Finding]) -> None:
+    behind: list[str] = []
+    for name, ver in detected.installed_pypi.items():
+        latest = version_snapshot.PYPI.get(name)
+        have = clean_version(ver)
+        if latest and have and compare_versions(have, latest) < 0:
+            behind.append(f"{name} {have} (installed) < {latest}")
+    for name, spec in detected.declared_pypi.items():
+        if name in detected.installed_pypi:
+            continue
+        latest = version_snapshot.PYPI.get(name)
+        if latest and range_blocks_latest(spec, latest):
+            behind.append(f'{name} "{spec}" excludes {latest}')
+    if behind:
+        out.append(
+            Finding(
+                "warn",
+                "A Cendor package looks behind the latest release",
+                f"An installed or pinned version trails the bundled snapshot (as of {version_snapshot.AS_OF}). "
+                "Type Teach and fixes only arrive on upgrade. This is an offline hint — /releases is canonical.",
+                'pip install -U "cendor-sdk"  (check https://cendor.ai/releases)',
+                behind,
+            )
+        )
+
+
+def run_doctor(root: Path) -> DoctorResult:
+    root = Path(root)
+    detected = detect_project(root)
+    src = _index(root)
+    count, uses = _usage(src)
+    findings: list[Finding] = []
+
+    _check_stray_init(root, src, findings)
+    _check_bare_import(root, src, findings)
+    _check_instrument(count, uses, findings)
+    _check_money(root, src, findings)
+
+    if detected.python:
+        _check_py_providers(detected, src, findings)
+        _check_py_versions(detected, findings)
+
+    if detected.node:
+        findings.append(
+            Finding(
+                "info",
+                "Node project detected",
+                "This CLI checks the Python ecosystem exactly. For the npm ecosystem (peer deps, "
+                "@cendor/* versions), run `npx @cendor/init doctor` from the same project.",
+            )
+        )
+
+    has_cendor = (
+        uses
+        or bool(detected.installed_pypi)
+        or bool(detected.declared_pypi)
+        or bool(detected.declared_npm)
+    )
+    if not has_cendor:
+        findings.insert(
+            0,
+            Finding(
+                "info",
+                "No Cendor usage detected",
+                "Found no Cendor imports or dependencies in this project — nothing to validate.",
+                "Run `uvx cendor-init` to wire Cendor + your AI assistant in one step.",
+            ),
+        )
+    elif not any(f.severity in ("error", "warn") for f in findings):
+        findings.append(
+            Finding(
+                "ok",
+                "Wiring looks good",
+                f"Cendor usage found{f', instrument() called {count}×' if count else ''}; no problems detected.",
+            )
+        )
+
+    exit_code = 1 if any(f.severity == "error" for f in findings) else 0
+    return DoctorResult(findings=findings, exit_code=exit_code)
+
+
+SEVERITY_RANK = {"error": 0, "warn": 1, "info": 2, "ok": 3}