convergent-cli 0.1.0__py3-none-any.whl

convergent_cli/state.py

@@ -0,0 +1,297 @@
+"""Local profile state for the CLI."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import secrets
+import stat
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from pathlib import Path
+from types import MappingProxyType
+from urllib.parse import urlparse
+
+from convergent_cli.errors import UsageError
+
+SCHEMA_VERSION = 1
+ENV_CONFIG_FILE = "CONVERGENT_CLI_CONFIG"
+ENV_PROFILE = "CONVERGENT_CLI_PROFILE"
+DEFAULT_PROFILE_NAME = "default"
+DEFAULT_ORIGIN = "https://app.convergent.dev"
+
+_PROFILE_NAME = re.compile(r"[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}\Z")
+
+
+class ConfigError(UsageError):
+    """The local cv config cannot be used."""
+
+
+class UnknownProfileError(ConfigError):
+    """A profile name was valid but not configured."""
+
+
+@dataclass(frozen=True, slots=True)
+class Profile:
+    origin: str
+    workspace_id: str | None = None
+
+    @classmethod
+    def parse(cls, name: str, raw: object) -> Profile:
+        if not isinstance(raw, dict):
+            raise ConfigError(f"profile {name!r} must be an object")
+        extra = set(raw) - {"origin", "workspace_id"}
+        if extra:
+            unsupported = ", ".join(sorted(extra))
+            raise ConfigError(f"profile {name!r} has unsupported fields: {unsupported}")
+        origin = raw.get("origin")
+        if not isinstance(origin, str):
+            raise ConfigError(f"profile {name!r} must declare an origin")
+        workspace_id = raw.get("workspace_id")
+        if workspace_id is not None and not isinstance(workspace_id, str):
+            raise ConfigError(f"profile {name!r} workspace_id must be a string")
+        return cls(
+            origin=validate_origin(origin),
+            workspace_id=validate_workspace_id(workspace_id) if workspace_id is not None else None,
+        )
+
+    def to_json(self) -> dict[str, str]:
+        payload = {"origin": self.origin}
+        if self.workspace_id is not None:
+            payload["workspace_id"] = self.workspace_id
+        return payload
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    active_profile: str
+    profiles: Mapping[str, Profile]
+    schema_version: int = SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "profiles", MappingProxyType(dict(self.profiles)))
+
+    @classmethod
+    def parse(cls, raw: object) -> Config:
+        if not isinstance(raw, dict):
+            raise ConfigError("config must be a JSON object")
+        extra = set(raw) - {"schema_version", "active_profile", "profiles"}
+        if extra:
+            raise ConfigError(f"config has unsupported fields: {', '.join(sorted(extra))}")
+
+        version = raw.get("schema_version")
+        if type(version) is int and version > SCHEMA_VERSION:
+            raise ConfigError(
+                f"config schema version {version} is newer than this cv supports ({SCHEMA_VERSION})"
+            )
+        if type(version) is not int or version != SCHEMA_VERSION:
+            raise ConfigError(f"config schema version must be {SCHEMA_VERSION}")
+
+        active_profile = raw.get("active_profile")
+        if not isinstance(active_profile, str):
+            raise ConfigError("active_profile must be a string")
+        validate_profile_name(active_profile)
+
+        raw_profiles = raw.get("profiles")
+        if not isinstance(raw_profiles, dict) or not raw_profiles:
+            raise ConfigError("profiles must be a non-empty object")
+
+        profiles = {
+            validate_profile_name(name): Profile.parse(name, profile)
+            for name, profile in raw_profiles.items()
+            if isinstance(name, str)
+        }
+        if len(profiles) != len(raw_profiles):
+            raise ConfigError("profile names must be strings")
+        if active_profile not in profiles:
+            raise ConfigError(f"active profile {active_profile!r} is not configured")
+        return cls(active_profile=active_profile, profiles=profiles)
+
+    def profile(self, name: str) -> Profile:
+        try:
+            return self.profiles[validate_profile_name(name)]
+        except KeyError as exc:
+            known = ", ".join(sorted(self.profiles))
+            message = f"no profile named {name!r} (known profiles: {known})"
+            raise UnknownProfileError(message) from exc
+
+    def with_active_profile(self, name: str) -> Config:
+        profile_name = validate_profile_name(name)
+        if profile_name not in self.profiles:
+            known = ", ".join(sorted(self.profiles))
+            raise UnknownProfileError(f"no profile named {name!r} (known profiles: {known})")
+        return Config(active_profile=profile_name, profiles=self.profiles)
+
+    def with_profile(self, name: str, profile: Profile) -> Config:
+        profile_name = validate_profile_name(name)
+        profiles = dict(self.profiles)
+        profiles[profile_name] = profile
+        return Config(active_profile=self.active_profile, profiles=profiles)
+
+    def with_profile_origin(self, name: str, origin: str) -> Config:
+        profile_name = validate_profile_name(name)
+        next_origin = validate_origin(origin)
+        existing = self.profiles.get(profile_name)
+        workspace_id = (
+            existing.workspace_id
+            if existing is not None and existing.origin == next_origin
+            else None
+        )
+        return self.with_profile(
+            profile_name,
+            Profile(origin=next_origin, workspace_id=workspace_id),
+        )
+
+    def with_profile_workspace(self, name: str, workspace_id: str | None) -> Config:
+        profile_name = validate_profile_name(name)
+        profile = self.profile(profile_name)
+        profiles = dict(self.profiles)
+        profiles[profile_name] = replace(
+            profile,
+            workspace_id=validate_workspace_id(workspace_id) if workspace_id is not None else None,
+        )
+        return Config(active_profile=self.active_profile, profiles=profiles)
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "schema_version": self.schema_version,
+            "active_profile": self.active_profile,
+            "profiles": {name: self.profiles[name].to_json() for name in sorted(self.profiles)},
+        }
+
+
+DEFAULT_PROFILE = Profile(DEFAULT_ORIGIN)
+
+
+def validate_profile_name(name: str) -> str:
+    if not _PROFILE_NAME.fullmatch(name):
+        raise ConfigError(
+            f"{name!r} is not a usable profile name; use letters, digits, dot, dash, "
+            "or underscore, up to 64 characters, and do not start with a dot"
+        )
+    return name
+
+
+def validate_origin(origin: str) -> str:
+    stripped = origin.strip().rstrip("/")
+    parsed = urlparse(stripped)
+    if parsed.scheme != "https" or not parsed.netloc:
+        raise ConfigError(f"origin {origin!r} must be an https URL")
+    if parsed.username is not None or parsed.password is not None:
+        raise ConfigError(f"origin {origin!r} must not include username or password")
+    try:
+        _ = parsed.port
+    except ValueError as exc:
+        raise ConfigError(f"origin {origin!r} must include a valid port") from exc
+    if not parsed.hostname:
+        raise ConfigError(f"origin {origin!r} must include a hostname")
+    if parsed.path or parsed.params or parsed.query or parsed.fragment:
+        raise ConfigError(f"origin {origin!r} must not include a path, query, or fragment")
+    return stripped
+
+
+def validate_workspace_id(workspace_id: str) -> str:
+    stripped = workspace_id.strip()
+    if not stripped:
+        raise ConfigError("workspace_id must not be empty")
+    if any(character in stripped for character in "\r\n\t"):
+        raise ConfigError("workspace_id must not include control whitespace")
+    return stripped
+
+
+def default_config() -> Config:
+    return Config(
+        active_profile=DEFAULT_PROFILE_NAME,
+        profiles={DEFAULT_PROFILE_NAME: DEFAULT_PROFILE},
+    )
+
+
+def config_path() -> Path:
+    override = os.environ.get(ENV_CONFIG_FILE)
+    if override:
+        return Path(override).expanduser()
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg).expanduser() if xdg else Path.home() / ".config"
+    return base / "convergent-cli" / "config.json"
+
+
+def active_profile_name(config: Config) -> str:
+    # Like --profile, the override lasts one invocation and never reaches the file.
+    override = os.environ.get(ENV_PROFILE)
+    if not override:
+        return config.active_profile
+    config.profile(override)
+    return validate_profile_name(override)
+
+
+def load_config() -> Config:
+    path = config_path()
+    if not path.exists():
+        return default_config()
+    require_safe_file(path)
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"{path} is not valid JSON ({exc.msg} at line {exc.lineno})") from exc
+    return Config.parse(raw)
+
+
+def save_config(config: Config) -> Path:
+    config.profile(config.active_profile)
+    path = config_path()
+    make_private_dir(path.parent)
+    write_private_file(path, json.dumps(config.to_json(), indent=2, sort_keys=True) + "\n")
+    return path
+
+
+def make_private_dir(path: Path) -> None:
+    missing: list[Path] = []
+    probe = path
+    while not probe.exists():
+        missing.append(probe)
+        probe = probe.parent
+    for directory in reversed(missing):
+        directory.mkdir(mode=0o700, exist_ok=True)
+    require_safe_dir(path)
+
+
+def require_safe_dir(path: Path) -> None:
+    if not path.exists():
+        return
+    if not path.is_dir():
+        raise ConfigError(f"config directory {path} is not a directory")
+    if os.name != "posix":
+        return
+    mode = path.stat().st_mode
+    if mode & (stat.S_IWGRP | stat.S_IWOTH):
+        raise ConfigError(f"config directory {path} is writable by the group or others")
+
+
+def require_safe_file(path: Path) -> None:
+    if path.is_symlink():
+        raise ConfigError(f"config file {path} is a symlink")
+    mode = path.stat().st_mode
+    if not stat.S_ISREG(mode):
+        raise ConfigError(f"config file {path} is not a regular file")
+    if os.name != "posix":
+        return
+    if mode & (stat.S_IWGRP | stat.S_IWOTH):
+        raise ConfigError(f"config file {path} is writable by the group or others")
+
+
+def write_private_file(path: Path, contents: str) -> None:
+    temp = path.with_name(f".{path.name}.{secrets.token_hex(8)}.tmp")
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
+    descriptor = os.open(temp, flags, 0o600)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(contents)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp, path)
+        if os.name == "posix":
+            path.chmod(0o600)
+    except BaseException:
+        temp.unlink(missing_ok=True)
+        raise

convergent_cli/transport.py

@@ -0,0 +1,242 @@
+"""Tiny JSON/form HTTP transport for the public CLI."""
+
+from __future__ import annotations
+
+import http.client
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Mapping
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any, Protocol
+
+from convergent_cli.errors import ApiError, AuthError, InvalidResponseError, NetworkError
+
+_HTTP_TIMEOUT_SECONDS = 15.0
+
+
+@dataclass(frozen=True, slots=True)
+class HttpResponse:
+    status_code: int
+    url: str
+    body: bytes
+    headers: Mapping[str, str]
+
+    def json(self) -> object:
+        try:
+            return json.loads(self.body.decode("utf-8"))
+        except (UnicodeDecodeError, ValueError) as exc:
+            raise InvalidResponseError(f"{self.url} did not answer with JSON") from exc
+
+
+class Transport(Protocol):
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        body: bytes | None = None,
+        timeout: float | None = None,
+    ) -> HttpResponse: ...
+
+
+def _user_agent() -> str:
+    # WorkOS's default authkit.app domain answers 403 to urllib's own user agent.
+    try:
+        return f"cv/{version('convergent-cli')}"
+    except PackageNotFoundError:
+        return "cv"
+
+
+_USER_AGENT = _user_agent()
+
+
+class UrllibTransport:
+    def __init__(self, opener: urllib.request.OpenerDirector | None = None) -> None:
+        self._opener = opener or urllib.request.build_opener(_NoRedirectHandler)
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        body: bytes | None = None,
+        timeout: float | None = None,
+    ) -> HttpResponse:
+        _require_https(url)
+        sent = {"User-Agent": _USER_AGENT, **(headers or {})}
+        request = urllib.request.Request(url, data=body, headers=sent, method=method)
+        try:
+            try:
+                response = self._opener.open(
+                    request, timeout=_HTTP_TIMEOUT_SECONDS if timeout is None else timeout
+                )
+            except urllib.error.HTTPError as exc:
+                response = exc
+            except urllib.error.URLError as exc:
+                raise NetworkError(f"{url} could not be reached: {exc.reason}") from exc
+            with response:
+                return HttpResponse(
+                    status_code=response.status,
+                    url=url,
+                    body=response.read(),
+                    headers=dict(response.headers.items()),
+                )
+        except (http.client.HTTPException, OSError) as exc:
+            raise NetworkError(f"{url} failed before a complete response: {exc!r}") from exc
+
+
+def get_json(transport: Transport, url: str, *, headers: Mapping[str, str] | None = None) -> object:
+    response = transport.request(
+        "GET",
+        url,
+        headers={"Accept": "application/json", **(headers or {})},
+    )
+    _require_success(response)
+    return response.json()
+
+
+def post_form(transport: Transport, url: str, data: Mapping[str, str]) -> HttpResponse:
+    body = urllib.parse.urlencode(data).encode("utf-8")
+    return transport.request(
+        "POST",
+        url,
+        headers={
+            "Accept": "application/json",
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body=body,
+    )
+
+
+def post_json(
+    transport: Transport,
+    url: str,
+    data: Mapping[str, object],
+    *,
+    headers: Mapping[str, str] | None = None,
+    timeout: float | None = None,
+) -> HttpResponse:
+    return _send_json(transport, "POST", url, data, headers=headers, timeout=timeout)
+
+
+def patch_json(
+    transport: Transport,
+    url: str,
+    data: Mapping[str, object],
+    *,
+    headers: Mapping[str, str] | None = None,
+) -> HttpResponse:
+    return _send_json(transport, "PATCH", url, data, headers=headers)
+
+
+def _send_json(
+    transport: Transport,
+    method: str,
+    url: str,
+    data: Mapping[str, object],
+    *,
+    headers: Mapping[str, str] | None,
+    timeout: float | None = None,
+) -> HttpResponse:
+    body = json.dumps(dict(data), separators=(",", ":")).encode("utf-8")
+    extra: dict[str, float] = {}
+    if timeout is not None:
+        extra["timeout"] = timeout
+    return transport.request(
+        method,
+        url,
+        headers={
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            **(headers or {}),
+        },
+        body=body,
+        **extra,
+    )
+
+
+def put_json(
+    transport: Transport,
+    url: str,
+    data: Mapping[str, object],
+    *,
+    headers: Mapping[str, str] | None = None,
+    timeout: float | None = None,
+) -> HttpResponse:
+    body = json.dumps(dict(data), ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    extra: dict[str, float] = {}
+    if timeout is not None:
+        extra["timeout"] = timeout
+    return transport.request(
+        "PUT",
+        url,
+        headers={
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            **(headers or {}),
+        },
+        body=body,
+        **extra,
+    )
+
+
+def require_json_object(value: object, *, url: str) -> Mapping[str, object]:
+    if not isinstance(value, dict):
+        raise InvalidResponseError(f"{url} did not answer with a JSON object")
+    return value
+
+
+def _require_success(response: HttpResponse) -> None:
+    if 200 <= response.status_code < 300:
+        return
+    raise ApiError(f"{response.url} answered {response.status_code}{_oauth_error(response)}")
+
+
+def _oauth_error(response: HttpResponse) -> str:
+    try:
+        body = response.json()
+    except AuthError:
+        return ""
+    code = body.get("error") if isinstance(body, dict) else None
+    if not isinstance(code, str) or not code:
+        return ""
+    shown = "".join(character for character in code if character.isprintable())[:80]
+    return f" ({shown})"
+
+
+def _require_https(url: str) -> None:
+    parsed = urllib.parse.urlsplit(url)
+    if parsed.scheme != "https":
+        raise AuthError(
+            f"refusing to send an HTTP request over {parsed.scheme or 'an unknown scheme'}"
+        )
+    if parsed.username is not None or parsed.password is not None:
+        raise AuthError("refusing to send an HTTP request to a URL with username or password")
+    try:
+        _ = parsed.port
+    except ValueError as exc:
+        raise AuthError("refusing to send an HTTP request to a URL with an invalid port") from exc
+    if not parsed.hostname:
+        raise AuthError("refusing to send an HTTP request to a URL without a hostname")
+
+
+class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    def http_error_301(
+        self,
+        req: urllib.request.Request,
+        fp: Any,
+        code: int,
+        msg: str,
+        headers: Any,
+    ) -> None:
+        raise urllib.error.HTTPError(req.full_url, code, msg, headers, fp)
+
+    http_error_302 = http_error_301
+    http_error_303 = http_error_301
+    http_error_307 = http_error_301
+    http_error_308 = http_error_301

convergent_cli/verdict_feedback.py

@@ -0,0 +1,161 @@
+"""Verdict feedback writes shared by ``cv verdicts review`` and ``cv findings review``.
+
+Both match one of the product UI's thumbs and post to
+``POST /v1/grades/{grade_id}/feedback``: the scorecard thumbs send no
+``finding_id`` (whole grade), and the finding card thumbs send the
+``finding_id`` of one finding. Neither reads the finding first; the
+route answers 404 for an unknown verdict and 422 for a finding that is not on
+the verdict.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Mapping
+from datetime import datetime
+from hashlib import sha256
+from re import fullmatch
+from urllib.parse import quote
+
+from convergent_cli import customer_client
+from convergent_cli.confirm import confirm_write
+from convergent_cli.errors import InvalidResponseError, UsageError
+from convergent_cli.output import emit_json
+
+GRADES_PATH = "/v1/grades"
+REASON_MAX_BYTES = 500
+_JUDGMENT_TO_FEEDBACK = {"correct": "positive", "incorrect": "negative"}
+_OCCURRENCE_ID_PATTERN = r"occ_[0-9a-f]{64}"
+
+
+def add_review_arguments(parser: argparse.ArgumentParser, *, subject: str) -> None:
+    """The judgment, reason, and format flags both review commands take."""
+    parser.add_argument(
+        "--judgment",
+        choices=tuple(_JUDGMENT_TO_FEEDBACK),
+        required=True,
+        help=f"Whether the {subject} is correct (thumbs up) or incorrect (thumbs down).",
+    )
+    parser.add_argument(
+        "--reason",
+        required=True,
+        help=f"Why the {subject} is correct or incorrect. Required, at most 500 UTF-8 bytes.",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("json",),
+        default=None,
+        help="Print the feedback receipt as JSON.",
+    )
+
+
+def review(args: argparse.Namespace, *, occurrence_id: str | None) -> int:
+    """Confirm, then record feedback on the verdict, or on one finding of it."""
+    verdict_id = _require_verdict_id(args.verdict_id)
+    if occurrence_id is not None:
+        occurrence_id = _require_occurrence_id(occurrence_id)
+    reason = _require_reason(args.reason)
+    value = _JUDGMENT_TO_FEEDBACK[args.judgment]
+    client = customer_client.HostedClient.for_active_profile()
+    confirm_write(_prompt(verdict_id, occurrence_id, args.judgment, reason))
+    raw_receipt = client.customer_post(
+        f"{GRADES_PATH}/{quote(verdict_id, safe='')}/feedback",
+        {"value": value, "comment": reason, "finding_id": occurrence_id},
+        idempotency_key=_idempotency_key(verdict_id, occurrence_id, value, reason),
+    )
+    result = _receipt(raw_receipt, verdict_id=verdict_id, occurrence_id=occurrence_id, value=value)
+    if args.format == "json":
+        emit_json(result)
+    else:
+        target = f"occurrence {occurrence_id} of verdict" if occurrence_id else "verdict"
+        print(
+            f"Marked {target} {verdict_id} {args.judgment}: {result['value']} "
+            f"feedback {result['feedback_id']} recorded."
+        )
+    return 0
+
+
+def _idempotency_key(verdict_id: str, occurrence_id: str | None, value: str, reason: str) -> str:
+    # One key per (verdict, finding, value, reason), so a retry replays its
+    # receipt and the same reason at the two levels does not share a key.
+    target = f"{verdict_id}\0{occurrence_id}" if occurrence_id else verdict_id
+    return sha256(f"review-finding\0{target}\0{value}\0{reason}".encode()).hexdigest()
+
+
+def _require_verdict_id(verdict_id: str) -> str:
+    cleaned = verdict_id.strip()
+    if not cleaned:
+        raise UsageError("verdict id must not be empty")
+    return cleaned
+
+
+def _require_occurrence_id(occurrence_id: str) -> str:
+    if fullmatch(_OCCURRENCE_ID_PATTERN, occurrence_id) is None:
+        raise UsageError(
+            "occurrence id must be an occurrence_id (occ_...) from cv findings list or get"
+        )
+    return occurrence_id
+
+
+def _require_reason(reason: str) -> str:
+    if not reason.strip():
+        raise UsageError("reason must not be empty")
+    if len(reason.encode()) > REASON_MAX_BYTES:
+        raise UsageError(f"reason must be at most {REASON_MAX_BYTES} UTF-8 bytes")
+    return reason
+
+
+def _prompt(verdict_id: str, occurrence_id: str | None, judgment: str, reason: str) -> str:
+    return (
+        "This will write one feedback record.\n"
+        f"Verdict id: {verdict_id}\n"
+        f"Occurrence id: {occurrence_id or 'none (whole verdict)'}\n"
+        f"Judgment: {judgment}\n"
+        f"Reason: {reason}"
+    )
+
+
+def _receipt(
+    payload: Mapping[str, object],
+    *,
+    verdict_id: str,
+    occurrence_id: str | None,
+    value: str,
+) -> dict[str, object]:
+    feedback_id = _required_string(payload, "feedback_id")
+    if fullmatch(r"vfb_[0-9a-f]{32}", feedback_id) is None:
+        raise InvalidResponseError("feedback response returned no usable feedback_id")
+    if _required_string(payload, "grade_id") != verdict_id:
+        raise InvalidResponseError("feedback response returned the wrong grade_id")
+    if payload.get("finding_id") != occurrence_id:
+        raise InvalidResponseError("feedback response returned the wrong finding_id")
+    if _required_string(payload, "value") != value:
+        raise InvalidResponseError("feedback response returned the wrong value")
+    comment = payload.get("comment")
+    if comment is not None and not isinstance(comment, str):
+        raise InvalidResponseError("feedback response returned no usable comment")
+    created_at = _required_string(payload, "created_at")
+    try:
+        parsed_created_at = datetime.fromisoformat(created_at)
+    except ValueError as exc:
+        raise InvalidResponseError("feedback response returned no usable created_at") from exc
+    if parsed_created_at.tzinfo is None:
+        raise InvalidResponseError("feedback response returned no usable created_at")
+    return {
+        "feedback_id": feedback_id,
+        "verdict_id": verdict_id,
+        "occurrence_id": occurrence_id,
+        "value": value,
+        "comment": comment,
+        "created_at": created_at,
+    }
+
+
+def _required_string(payload: Mapping[str, object], field: str) -> str:
+    value = payload.get(field)
+    if not isinstance(value, str) or not value:
+        raise InvalidResponseError(f"feedback response returned no usable {field}")
+    return value
+
+
+__all__ = ["add_review_arguments", "review"]