coderouter-cli 1.7.0__py3-none-any.whl

coderouter/env_security.py

@@ -0,0 +1,434 @@
+"""`.env` file security checks (v1.6.3).
+
+Run from ``coderouter doctor --check-env [PATH]`` to surface the three
+common ``.env`` mishaps before they bite:
+
+  1. **Filesystem permissions** — on POSIX, the file should be readable
+     only by the owner (``mode & 0o077 == 0``). World/group readable
+     ``.env`` exposes API keys to other accounts on shared machines and
+     to backup tools that recurse with broad scope.
+  2. **`.gitignore` coverage** — ``.env`` MUST be matched by the repo's
+     ignore rules so an absent-minded ``git add .`` doesn't stage it.
+  3. **`git` tracking state** — if ``.env`` is already tracked
+     (committed in the past), no ``.gitignore`` rule will save it. The
+     fix is to ``git rm --cached``, rotate the leaked keys, and update
+     ``.gitignore``.
+
+Design choices
+--------------
+* Pure stdlib (``os`` / ``stat`` / ``subprocess`` / ``shutil``) so we
+  preserve the runtime-deps freeze (5 packages — see plan.md §5.4).
+* No HTTP, no asyncio — these are local filesystem and git checks, so
+  the module is intentionally separate from ``coderouter.doctor``
+  (which is httpx-heavy). The CLI surfaces both via the same
+  ``coderouter doctor`` namespace.
+* Verdict severity is mapped to the same exit-code contract used by
+  the model probes (0 OK / 2 patchable / 1 blocker), so wrappers like
+  ``coderouter doctor --check-env --check-model nim-x`` (a v1.7
+  candidate) can collapse the verdicts uniformly.
+* Windows: file-mode check is skipped with verdict SKIP (Windows POSIX
+  bits are unreliable). Git checks still run if ``git`` is on PATH.
+
+Non-destructive contract
+------------------------
+This module never writes, never deletes, never invokes ``git add`` or
+``git rm``. It only reads filesystem metadata and runs read-only git
+plumbing (``git check-ignore`` / ``git ls-files --error-unmatch``).
+The repo state is not mutated.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+import subprocess
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+
+__all__ = [
+    "EnvSecurityCheck",
+    "EnvSecurityReport",
+    "EnvSecurityVerdict",
+    "check_env_security",
+    "exit_code_for_env_security",
+    "format_env_security_report",
+]
+
+
+class EnvSecurityVerdict(StrEnum):
+    """Per-check verdict.
+
+    Mapping to exit code (see :func:`exit_code_for_env_security`):
+        OK    → contributes 0
+        SKIP  → contributes 0 (not applicable, e.g. Windows file-mode)
+        WARN  → contributes 2 (fix recommended; chmod / .gitignore edit)
+        ERROR → contributes 1 (real leak risk; .env is git-tracked, etc.)
+    """
+
+    OK = "ok"
+    SKIP = "skip"
+    WARN = "warn"
+    ERROR = "error"
+
+
+@dataclass
+class EnvSecurityCheck:
+    """Outcome of a single check in the env-security suite.
+
+    ``fix`` is a 1-line shell command (or short snippet) the operator
+    can copy-paste to remediate. ``None`` when no remediation is
+    applicable (e.g. on a SKIP verdict).
+    """
+
+    name: str
+    verdict: EnvSecurityVerdict
+    detail: str
+    fix: str | None = None
+
+
+@dataclass
+class EnvSecurityReport:
+    """Aggregate report for a single ``--check-env`` invocation."""
+
+    path: Path
+    checks: list[EnvSecurityCheck] = field(default_factory=list)
+
+
+def exit_code_for_env_security(report: EnvSecurityReport) -> int:
+    """Derive the CLI exit code from a report (see :class:`EnvSecurityVerdict`).
+
+    Same shape as :func:`coderouter.doctor.exit_code_for` so callers
+    can union the two reports without special-casing.
+    """
+    has_blocker = False
+    has_warn = False
+    for c in report.checks:
+        if c.verdict == EnvSecurityVerdict.ERROR:
+            has_blocker = True
+        elif c.verdict == EnvSecurityVerdict.WARN:
+            has_warn = True
+    if has_blocker:
+        return 1
+    if has_warn:
+        return 2
+    return 0
+
+
+def check_env_security(
+    path: str | os.PathLike[str],
+    *,
+    git_executable: str | None = None,
+) -> EnvSecurityReport:
+    """Run the 3-check env-security suite against ``path``.
+
+    The checks are independent — each runs even if a previous one
+    failed, so the report shows everything wrong at once (rather than
+    making the user fix one thing, re-run, see the next, etc.).
+
+    Args:
+        path: ``.env`` file to inspect. Does not need to exist; if
+            absent, all checks return SKIP with a clear message so
+            the operator can ack ("yeah, I haven't created one yet").
+        git_executable: Override the ``git`` binary path; primarily
+            for tests. Defaults to ``shutil.which("git")``.
+
+    Returns:
+        :class:`EnvSecurityReport` with one entry per check (in
+        deterministic order: existence, perms, gitignore, tracking).
+    """
+    p = Path(path).resolve()
+    report = EnvSecurityReport(path=p)
+
+    # -------------------------------------------------------------- #
+    # Check 0: existence
+    # -------------------------------------------------------------- #
+    if not p.exists():
+        report.checks.append(
+            EnvSecurityCheck(
+                name="existence",
+                verdict=EnvSecurityVerdict.SKIP,
+                detail=f"no file at {p} — nothing to inspect",
+                fix=None,
+            )
+        )
+        # Bail early: nothing to inspect, but report SKIP for the
+        # remaining checks so the output stays consistent.
+        report.checks.append(_skip("permissions", "no file to inspect"))
+        report.checks.append(_skip("gitignore", "no file to inspect"))
+        report.checks.append(_skip("git-tracking", "no file to inspect"))
+        return report
+
+    if not p.is_file():
+        report.checks.append(
+            EnvSecurityCheck(
+                name="existence",
+                verdict=EnvSecurityVerdict.ERROR,
+                detail=f"path exists but is not a regular file: {p}",
+                fix=None,
+            )
+        )
+        return report
+
+    report.checks.append(
+        EnvSecurityCheck(
+            name="existence",
+            verdict=EnvSecurityVerdict.OK,
+            detail=f"found at {p}",
+        )
+    )
+
+    # -------------------------------------------------------------- #
+    # Check 1: permissions (POSIX only — Windows bits are unreliable)
+    # -------------------------------------------------------------- #
+    report.checks.append(_check_permissions(p))
+
+    # -------------------------------------------------------------- #
+    # Check 2: .gitignore coverage
+    # Check 3: git-tracking state
+    # Both depend on `git`. If git is unavailable, both SKIP with the
+    # same explanatory message so users on a non-git checkout aren't
+    # spammed with "git not found" twice.
+    # -------------------------------------------------------------- #
+    git_bin = git_executable or shutil.which("git")
+    if not git_bin:
+        report.checks.append(
+            _skip("gitignore", "git not on PATH — cannot evaluate .gitignore")
+        )
+        report.checks.append(
+            _skip("git-tracking", "git not on PATH — cannot evaluate tracking")
+        )
+        return report
+
+    repo_root = _find_repo_root(p, git_bin)
+    if repo_root is None:
+        report.checks.append(
+            _skip("gitignore", "not inside a git repository")
+        )
+        report.checks.append(
+            _skip("git-tracking", "not inside a git repository")
+        )
+        return report
+
+    report.checks.append(_check_gitignore(p, repo_root, git_bin))
+    report.checks.append(_check_git_tracking(p, repo_root, git_bin))
+
+    return report
+
+
+def format_env_security_report(report: EnvSecurityReport) -> str:
+    """Render an :class:`EnvSecurityReport` as a human-readable block.
+
+    Output is intentionally similar in shape to
+    :func:`coderouter.doctor.format_report` (header line, indented
+    detail, fix command on a separate indented line) so the two
+    reports can sit next to each other without visual whiplash.
+    """
+    lines: list[str] = []
+    lines.append("─" * 60)
+    lines.append(f"env-security: {report.path}")
+    lines.append("Checks:")
+    for c in report.checks:
+        lines.append(f"  [{c.verdict.value.upper():6s}] {c.name}")
+        lines.append(f"      {c.detail}")
+        if c.fix:
+            lines.append(f"      fix: {c.fix}")
+
+    has_warn = any(c.verdict == EnvSecurityVerdict.WARN for c in report.checks)
+    has_err = any(c.verdict == EnvSecurityVerdict.ERROR for c in report.checks)
+    if has_err:
+        summary = "Summary: at least one check escalated to ERROR (real leak risk)."
+    elif has_warn:
+        summary = "Summary: WARN(s) present — apply the suggested fix(es)."
+    else:
+        summary = "Summary: all checks pass."
+    lines.append(summary)
+    lines.append(f"Exit: {exit_code_for_env_security(report)}")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Internals
+# ---------------------------------------------------------------------------
+
+
+def _skip(name: str, reason: str) -> EnvSecurityCheck:
+    return EnvSecurityCheck(
+        name=name,
+        verdict=EnvSecurityVerdict.SKIP,
+        detail=reason,
+        fix=None,
+    )
+
+
+def _check_permissions(p: Path) -> EnvSecurityCheck:
+    """Verify ``.env`` is owner-only readable on POSIX systems."""
+    if os.name == "nt":
+        return _skip("permissions", "Windows — POSIX mode bits unreliable")
+
+    mode = p.stat().st_mode
+    perm = stat.S_IMODE(mode)
+    other_or_group = perm & 0o077
+    if other_or_group == 0:
+        return EnvSecurityCheck(
+            name="permissions",
+            verdict=EnvSecurityVerdict.OK,
+            detail=f"mode = {oct(perm)} (owner-only)",
+        )
+    return EnvSecurityCheck(
+        name="permissions",
+        verdict=EnvSecurityVerdict.WARN,
+        detail=(
+            f"mode = {oct(perm)} grants group/other access. API keys in "
+            f"this file are visible to other accounts on shared machines "
+            f"and to backup tools."
+        ),
+        fix=f"chmod 0600 {p}",
+    )
+
+
+def _find_repo_root(p: Path, git_bin: str) -> Path | None:
+    """Return the git repo root containing ``p``, or None if not in a repo.
+
+    Uses ``git rev-parse --show-toplevel`` from ``p``'s directory — the
+    cheapest way to ask git the question without parsing ``.git``
+    layouts ourselves (worktrees, submodules, ``GIT_DIR=...`` envs all
+    DTRT).
+    """
+    try:
+        result = subprocess.run(
+            [git_bin, "rev-parse", "--show-toplevel"],
+            cwd=p.parent,
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    root = result.stdout.strip()
+    if not root:
+        return None
+    return Path(root)
+
+
+def _check_gitignore(p: Path, repo_root: Path, git_bin: str) -> EnvSecurityCheck:
+    """Verify ``.env`` is matched by ``.gitignore`` (any rule).
+
+    ``git check-ignore`` exit codes:
+        0 = path IS ignored
+        1 = path is NOT ignored
+        128 = error (treated as ERROR verdict so the operator notices)
+    """
+    try:
+        result = subprocess.run(
+            [git_bin, "check-ignore", "-q", str(p)],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return EnvSecurityCheck(
+            name="gitignore",
+            verdict=EnvSecurityVerdict.SKIP,
+            detail=f"git check-ignore failed: {exc}",
+            fix=None,
+        )
+
+    if result.returncode == 0:
+        return EnvSecurityCheck(
+            name="gitignore",
+            verdict=EnvSecurityVerdict.OK,
+            detail=f"matched by .gitignore in {repo_root}",
+        )
+    if result.returncode == 1:
+        # Compute a relative path for the suggested fix when possible.
+        try:
+            rel = p.relative_to(repo_root)
+        except ValueError:
+            rel = p
+        return EnvSecurityCheck(
+            name="gitignore",
+            verdict=EnvSecurityVerdict.WARN,
+            detail=(
+                f"NOT matched by any .gitignore rule in {repo_root}. "
+                f"`git add .` from this repo will stage the file."
+            ),
+            fix=f'echo "{rel}" >> {repo_root}/.gitignore',
+        )
+    return EnvSecurityCheck(
+        name="gitignore",
+        verdict=EnvSecurityVerdict.SKIP,
+        detail=(
+            f"git check-ignore returned unexpected code {result.returncode}: "
+            f"{(result.stderr or result.stdout).strip()!r}"
+        ),
+        fix=None,
+    )
+
+
+def _check_git_tracking(p: Path, repo_root: Path, git_bin: str) -> EnvSecurityCheck:
+    """Verify ``.env`` is NOT currently tracked by git.
+
+    ``git ls-files --error-unmatch`` exit codes:
+        0 = path IS tracked
+        1 = path is NOT tracked (this is what we want)
+        other = error
+    """
+    try:
+        result = subprocess.run(
+            [git_bin, "ls-files", "--error-unmatch", str(p)],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return EnvSecurityCheck(
+            name="git-tracking",
+            verdict=EnvSecurityVerdict.SKIP,
+            detail=f"git ls-files failed: {exc}",
+            fix=None,
+        )
+
+    if result.returncode == 0:
+        try:
+            rel = p.relative_to(repo_root)
+        except ValueError:
+            rel = p
+        return EnvSecurityCheck(
+            name="git-tracking",
+            verdict=EnvSecurityVerdict.ERROR,
+            detail=(
+                f"file is currently tracked by git in {repo_root}. Any "
+                f"secrets in it have been (or could be) committed and "
+                f"pushed. .gitignore rules do NOT untrack already-"
+                f"tracked files."
+            ),
+            fix=(
+                f"git -C {repo_root} rm --cached {rel} && "
+                f"echo '{rel}' >> {repo_root}/.gitignore && "
+                f"# rotate any leaked keys, then commit"
+            ),
+        )
+    if result.returncode == 1:
+        return EnvSecurityCheck(
+            name="git-tracking",
+            verdict=EnvSecurityVerdict.OK,
+            detail=f"not tracked by git in {repo_root}",
+        )
+    return EnvSecurityCheck(
+        name="git-tracking",
+        verdict=EnvSecurityVerdict.SKIP,
+        detail=(
+            f"git ls-files returned unexpected code {result.returncode}: "
+            f"{(result.stderr or result.stdout).strip()!r}"
+        ),
+        fix=None,
+    )

coderouter/errors.py

@@ -0,0 +1,29 @@
+"""Root exception hierarchy.
+
+All CodeRouter-raised exceptions inherit from :class:`CodeRouterError` so
+callers (tests, embedders, downstream integrations) can catch "anything
+CodeRouter produced" with a single ``except CodeRouterError`` clause
+without having to import each leaf type individually.
+
+The concrete subclasses still live next to the code that raises them
+(:mod:`coderouter.adapters.base` for :class:`AdapterError`,
+:mod:`coderouter.routing.fallback` for :class:`NoProvidersAvailableError`
+and :class:`MidStreamError`) — this module only defines the root and
+re-exports the leaves for discoverability. Existing import paths are
+preserved; nothing has to change at call sites.
+"""
+
+from __future__ import annotations
+
+
+class CodeRouterError(Exception):
+    """Base class for every exception CodeRouter raises internally.
+
+    Exists so external code can write ``except CodeRouterError`` to catch
+    any failure the router itself produces, without having to enumerate
+    the leaves (which are free to grow over time). Does not add any
+    behavior beyond :class:`Exception`.
+    """
+
+
+__all__ = ["CodeRouterError"]

coderouter/ingress/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP ingress (OpenAI-compatible in v0.1; Anthropic-compatible coming v0.2)."""
+
+from coderouter.ingress.app import create_app
+
+__all__ = ["create_app"]

coderouter/ingress/anthropic_routes.py

@@ -0,0 +1,205 @@
+"""Anthropic-compatible route: POST /v1/messages.
+
+Accepts Anthropic Messages API requests and routes them through the
+engine's Anthropic-shaped entry points (`generate_anthropic` /
+`stream_anthropic`). For `kind: "anthropic"` providers the engine does
+direct passthrough; for `kind: "openai_compat"` providers it handles
+translation, tool-call repair, and the v0.3-D tool-turn downgrade.
+
+SSE streaming events follow the Anthropic wire protocol
+(`message_start` / `content_block_*` / `message_delta` / `message_stop`).
+
+Profile selection mirrors the OpenAI route (see openai_routes.py):
+    Body field `profile` > `X-CodeRouter-Profile` header >
+    `X-CodeRouter-Mode` header (v0.6-D, via mode_aliases) >
+    auto_router (v1.6-A, when ``default_profile: auto``) >
+    config default.
+
+`anthropic-version` header is accepted but not enforced — Claude Code and
+SDKs send values like "2023-06-01"; we log it for diagnostics only.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from typing import Any
+
+from fastapi import APIRouter, Header, HTTPException, Request
+from fastapi.responses import StreamingResponse
+
+from coderouter.logging import get_logger
+from coderouter.routing import (
+    FallbackEngine,
+    MidStreamError,
+    NoProvidersAvailableError,
+)
+from coderouter.routing.auto_router import RESERVED_PROFILE_NAME, classify
+from coderouter.translation import (
+    AnthropicRequest,
+    AnthropicStreamEvent,
+)
+
+router = APIRouter()
+logger = get_logger(__name__)
+
+_PROFILE_HEADER = "x-coderouter-profile"
+_MODE_HEADER = "x-coderouter-mode"
+_ANTHROPIC_VERSION_HEADER = "anthropic-version"
+_ANTHROPIC_BETA_HEADER = "anthropic-beta"
+
+
+@router.post("/messages", response_model=None)
+async def messages(
+    payload: dict[str, Any],
+    request: Request,
+    x_coderouter_profile: str | None = Header(default=None, alias=_PROFILE_HEADER),
+    x_coderouter_mode: str | None = Header(default=None, alias=_MODE_HEADER),
+    anthropic_version: str | None = Header(default=None, alias=_ANTHROPIC_VERSION_HEADER),
+    anthropic_beta: str | None = Header(default=None, alias=_ANTHROPIC_BETA_HEADER),
+) -> StreamingResponse | dict[str, Any]:
+    """Anthropic Messages API endpoint.
+
+    Validates the body into :class:`AnthropicRequest`, resolves the
+    profile (body > profile header > mode header > config default),
+    then dispatches to the engine's Anthropic-shaped entry points. For
+    streaming requests, returns a :class:`StreamingResponse` that
+    serializes engine events onto the Anthropic SSE wire; otherwise
+    returns the JSON response body.
+    """
+    engine: FallbackEngine = request.app.state.engine
+    config = request.app.state.config
+
+    if anthropic_version:
+        # Don't enforce — just trace. Future: match against a known list.
+        logger.debug(
+            "anthropic-version-header",
+            extra={"value": anthropic_version},
+        )
+
+    try:
+        anth_req = AnthropicRequest.model_validate(payload)
+    except Exception as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+    # v0.4-D: forward the `anthropic-beta` header through to the native
+    # adapter. Without this, any body field gated behind a beta header
+    # (`context_management`, newer cache_control/thinking variants, etc.)
+    # is rejected by api.anthropic.com with 400 "Extra inputs are not
+    # permitted". We stash it on the request model with exclude=True so
+    # the adapter can reach it without leaking into the wire body.
+    if anthropic_beta:
+        anth_req.anthropic_beta = anthropic_beta
+
+    # Profile selection — body field wins over header (same policy as OpenAI route).
+    if anth_req.profile is None and x_coderouter_profile:
+        anth_req.profile = x_coderouter_profile
+
+    # v0.6-D: X-CodeRouter-Mode → mode_aliases → profile. Mode sits below
+    # Profile because Mode is intent / Profile is the implementation.
+    if anth_req.profile is None and x_coderouter_mode:
+        try:
+            anth_req.profile = config.resolve_mode(x_coderouter_mode)
+        except KeyError as exc:
+            available = sorted(config.mode_aliases.keys())
+            raise HTTPException(
+                status_code=400,
+                detail=(f"unknown mode {x_coderouter_mode!r}. available modes: {available}"),
+            ) from exc
+        logger.info(
+            "mode-alias-resolved",
+            extra={"mode": x_coderouter_mode, "profile": anth_req.profile},
+        )
+
+    # v1.6-A: auto router slot. Symmetric with the OpenAI route — fires only
+    # when ``default_profile: auto`` is set and no explicit profile signal won
+    # above. When inactive the engine falls through to ``default_profile`` on
+    # its own. ``classify`` inspects the raw ``payload`` dict (not the
+    # AnthropicRequest), so both OpenAI and Anthropic ingress use the same
+    # classifier without a shared request shim.
+    if anth_req.profile is None and config.default_profile == RESERVED_PROFILE_NAME:
+        anth_req.profile = classify(payload, config)
+
+    if anth_req.profile is not None:
+        try:
+            config.profile_by_name(anth_req.profile)
+        except KeyError as exc:
+            available = [p.name for p in config.profiles]
+            raise HTTPException(
+                status_code=400,
+                detail=(f"unknown profile {anth_req.profile!r}. available: {available}"),
+            ) from exc
+
+    if anth_req.stream:
+        return StreamingResponse(
+            _anthropic_sse_iterator(engine, anth_req),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+        )
+
+    try:
+        anth_resp = await engine.generate_anthropic(anth_req)
+    except NoProvidersAvailableError as exc:
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+
+    return anth_resp.model_dump(exclude_none=True)
+
+
+async def _anthropic_sse_iterator(
+    engine: FallbackEngine, anth_req: AnthropicRequest
+) -> AsyncIterator[str]:
+    """Serialize engine.stream_anthropic() onto the Anthropic SSE wire.
+
+    Each emitted block is `event: <type>\\ndata: <json>\\n\\n` per the
+    Anthropic spec (distinct from OpenAI's `data:`-only format).
+    Errors map to in-stream `event: error` events — we never switch an
+    in-flight HTTP response to a 5xx once headers have shipped.
+    """
+    try:
+        async for ev in engine.stream_anthropic(anth_req):
+            yield _format_anthropic_sse(ev)
+    except NoProvidersAvailableError as exc:
+        # No provider produced even the first event — surface as overloaded.
+        err_event = AnthropicStreamEvent(
+            type="error",
+            data={
+                "type": "error",
+                "error": {
+                    "type": "overloaded_error",
+                    "message": str(exc),
+                },
+            },
+        )
+        yield _format_anthropic_sse(err_event)
+    except MidStreamError as exc:
+        # v0.3-B: a provider failed AFTER emitting at least one event. We
+        # cannot fall back (client already received partial content), so
+        # close the stream with an explicit error event. `api_error`
+        # distinguishes this from "no provider could start" (overloaded).
+        logger.warning(
+            "sse-midstream-error",
+            extra={"provider": exc.provider, "original": str(exc.original)},
+        )
+        err_event = AnthropicStreamEvent(
+            type="error",
+            data={
+                "type": "error",
+                "error": {
+                    "type": "api_error",
+                    "message": str(exc),
+                },
+            },
+        )
+        yield _format_anthropic_sse(err_event)
+
+
+def _format_anthropic_sse(ev: AnthropicStreamEvent) -> str:
+    """Serialize an :class:`AnthropicStreamEvent` onto the SSE wire.
+
+    Anthropic's SSE format requires both an ``event:`` and a ``data:``
+    line per frame (unlike OpenAI's ``data:``-only chunks). The event
+    name carries the type (``message_start`` / ``content_block_delta``
+    / ...) and the data line carries the JSON payload.
+    """
+    payload = json.dumps(ev.data, ensure_ascii=False)
+    return f"event: {ev.type}\ndata: {payload}\n\n"