ktr-cli 0.1.0__py3-none-any.whl

kantree_cli/core/__init__.py

@@ -0,0 +1 @@
+"""Core runtime helpers for ktr-cli."""

kantree_cli/core/client.py

@@ -0,0 +1,230 @@
+import time as _time
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlparse
+
+import requests
+
+from kantree_cli.core.errors import (
+    ApiError,
+    AuthError,
+    NetworkError,
+    NotFoundError,
+    PreconditionError,
+    ValidationError,
+)
+
+DEFAULT_TIMEOUT_SECONDS = 30.0
+DEFAULT_MAX_RETRIES = 3
+_RETRYABLE_STATUSES = frozenset({502, 503, 504})
+_IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+
+@dataclass(slots=True)
+class KantreeResponse:
+    status_code: int
+    data: Any
+    headers: dict[str, str]
+
+
+@dataclass(slots=True)
+class KantreeRawResponse:
+    status_code: int
+    content: bytes
+    headers: dict[str, str]
+
+
+class KantreeClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str | None,
+        timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        session: requests.Session | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._timeout_seconds = timeout_seconds
+        self._max_retries = max_retries
+        self._session = session or requests.Session()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        json_body: Any = None,
+        form_data: dict[str, str] | None = None,
+        files: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> KantreeResponse:
+        if json_body is not None and (form_data is not None or files is not None):
+            raise ValidationError("Use either a JSON payload or form-data/files payload, not both.")
+
+        target_url = self._build_url(path)
+        request_headers = {"Accept": "application/json"}
+        if self._api_key:
+            request_headers["X-Api-Key"] = self._api_key
+        if headers:
+            request_headers.update(headers)
+
+        upper_method = method.upper()
+        retryable = upper_method in _IDEMPOTENT_METHODS and self._max_retries > 0
+
+        for attempt in range(self._max_retries + 1):
+            if attempt > 0:
+                backoff = 2 ** (attempt - 1)
+                _time.sleep(backoff)
+
+            try:
+                response = self._session.request(
+                    method=upper_method,
+                    url=target_url,
+                    params=params,
+                    json=json_body,
+                    data=form_data,
+                    files=files,
+                    headers=request_headers,
+                    timeout=self._timeout_seconds,
+                )
+            except (requests.Timeout, requests.ConnectionError) as exc:
+                if retryable and attempt < self._max_retries:
+                    continue
+                raise NetworkError(
+                    f"Network request failed: {exc}"
+                    if not isinstance(exc, requests.Timeout)
+                    else f"Request timed out after {self._timeout_seconds:.0f}s"
+                ) from exc
+            except requests.RequestException as exc:
+                raise NetworkError(f"Network request failed: {exc}") from exc
+
+            if (
+                retryable
+                and response.status_code in _RETRYABLE_STATUSES
+                and attempt < self._max_retries
+            ):
+                continue
+
+            break
+
+        if response.status_code in (401, 403):
+            raise AuthError(f"Authentication failed ({response.status_code})")
+        if response.status_code == 404:
+            details = _extract_api_error_details(response)
+            raise NotFoundError(f"Resource not found for `{path}`: {details}")
+        if response.status_code == 412:
+            details = _extract_api_error_details(response)
+            raise PreconditionError(f"Precondition failed for `{path}`: {details}")
+        if response.status_code >= 400:
+            details = _extract_api_error_details(response)
+            raise ApiError(f"API request failed ({response.status_code}): {details}")
+
+        return KantreeResponse(
+            status_code=response.status_code,
+            data=_parse_response_data(response),
+            headers=dict(response.headers),
+        )
+
+    def get_json(self, path: str) -> Any:
+        response = self.request("GET", path)
+        return response.data
+
+    def download_same_origin_url(self, url: str) -> KantreeRawResponse:
+        target = urlparse(url)
+        base = urlparse(self._base_url)
+        if target.scheme not in {"http", "https"} or not target.netloc:
+            raise ValidationError("Artifact URL must be absolute.")
+        if (target.scheme, target.netloc) != (base.scheme, base.netloc):
+            raise ValidationError("Artifact URL must use the configured Kantree origin.")
+
+        request_headers = {"Accept": "*/*"}
+        if self._api_key:
+            request_headers["X-Api-Key"] = self._api_key
+
+        retryable = self._max_retries > 0
+        for attempt in range(self._max_retries + 1):
+            if attempt > 0:
+                backoff = 2 ** (attempt - 1)
+                _time.sleep(backoff)
+
+            try:
+                response = self._session.request(
+                    method="GET",
+                    url=url,
+                    headers=request_headers,
+                    timeout=self._timeout_seconds,
+                )
+            except (requests.Timeout, requests.ConnectionError) as exc:
+                if retryable and attempt < self._max_retries:
+                    continue
+                raise NetworkError(
+                    f"Network request failed: {exc}"
+                    if not isinstance(exc, requests.Timeout)
+                    else f"Request timed out after {self._timeout_seconds:.0f}s"
+                ) from exc
+            except requests.RequestException as exc:
+                raise NetworkError(f"Network request failed: {exc}") from exc
+
+            if (
+                retryable
+                and response.status_code in _RETRYABLE_STATUSES
+                and attempt < self._max_retries
+            ):
+                continue
+
+            break
+
+        if response.status_code in (401, 403):
+            raise AuthError(f"Authentication failed ({response.status_code})")
+        if response.status_code == 404:
+            details = _extract_api_error_details(response)
+            raise NotFoundError(f"Resource not found for artifact URL: {details}")
+        if response.status_code == 412:
+            details = _extract_api_error_details(response)
+            raise PreconditionError(f"Precondition failed for artifact URL: {details}")
+        if response.status_code >= 400:
+            details = _extract_api_error_details(response)
+            raise ApiError(f"API request failed ({response.status_code}): {details}")
+
+        return KantreeRawResponse(
+            status_code=response.status_code,
+            content=response.content,
+            headers=dict(response.headers),
+        )
+
+    def _build_url(self, path: str) -> str:
+        if path.lower().startswith(("http://", "https://")):
+            raise ValidationError(
+                "Path must be relative to the configured base URL; absolute URLs are not allowed."
+            )
+        if not path.startswith("/"):
+            path = f"/{path}"
+        return f"{self._base_url}{path}"
+
+
+def _extract_api_error_details(response: requests.Response) -> str:
+    payload = _parse_response_data(response)
+    if isinstance(payload, dict):
+        for key in ("error", "message", "detail", "description"):
+            value = payload.get(key)
+            if isinstance(value, str) and value.strip():
+                return value
+        errors_value = payload.get("errors")
+        if isinstance(errors_value, list):
+            parts = [str(item) for item in errors_value if item]
+            if parts:
+                return "; ".join(parts)
+        if isinstance(errors_value, str) and errors_value.strip():
+            return errors_value
+    text = response.text.strip()
+    return text if text else "unknown API error"
+
+
+def _parse_response_data(response: requests.Response) -> Any:
+    try:
+        return response.json()
+    except ValueError:
+        return response.text

kantree_cli/core/config.py

@@ -0,0 +1,226 @@
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from kantree_cli.core.errors import ValidationError
+
+DEFAULT_PROFILE = "default"
+DEFAULT_BASE_URL = "https://kantree.io/api/1.0"
+DEFAULT_API_KEY_ENV = "KANTREE_API_KEY"
+
+
+@dataclass(slots=True)
+class ProfileConfig:
+    base_url: str | None = None
+    api_key_env: str | None = None
+    default_workspace: str | None = None
+
+
+@dataclass(slots=True)
+class SearchPresetConfig:
+    kql: str
+    scope: str | None = None
+    default_format: str | None = None
+
+
+@dataclass(slots=True)
+class AppConfig:
+    active_profile: str | None = None
+    profiles: dict[str, ProfileConfig] = field(default_factory=dict)
+    search_presets: dict[str, SearchPresetConfig] = field(default_factory=dict)
+
+
+def config_path() -> Path:
+    return config_dir() / "config.toml"
+
+
+def config_dir() -> Path:
+    xdg_config_home = os.environ.get("XDG_CONFIG_HOME")
+    if xdg_config_home:
+        return Path(xdg_config_home).expanduser() / "kantree"
+    return Path.home() / ".config" / "kantree"
+
+
+def default_profile_config() -> ProfileConfig:
+    return ProfileConfig(base_url=DEFAULT_BASE_URL, api_key_env=DEFAULT_API_KEY_ENV)
+
+
+def default_app_config() -> AppConfig:
+    return AppConfig(
+        active_profile=DEFAULT_PROFILE,
+        profiles={DEFAULT_PROFILE: default_profile_config()},
+    )
+
+
+def load_config(path: Path | None = None) -> AppConfig:
+    path = path or config_path()
+    if not path.exists():
+        return AppConfig()
+
+    try:
+        import tomllib
+
+        parsed = tomllib.loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise ValidationError(f"Failed to read config file: {path}") from exc
+    except Exception as exc:
+        raise ValidationError(f"Invalid TOML in config file: {path}") from exc
+
+    return _parse_app_config(parsed)
+
+
+def save_config(config: AppConfig, path: Path | None = None) -> Path:
+    path = path or config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = _dump_app_config(config)
+
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as stream:
+            stream.write(data)
+    finally:
+        os.chmod(path, 0o600)
+
+    return path
+
+
+def ensure_default_config(path: Path | None = None) -> tuple[AppConfig, Path, bool]:
+    path = path or config_path()
+    if path.exists():
+        return load_config(path), path, False
+
+    config = default_app_config()
+    save_config(config, path)
+    return config, path, True
+
+
+def _parse_app_config(raw: dict[str, Any]) -> AppConfig:
+    active_profile = raw.get("active_profile")
+    if active_profile is not None and not isinstance(active_profile, str):
+        raise ValidationError("`active_profile` must be a string in config.toml")
+
+    raw_profiles = raw.get("profiles", {})
+    if raw_profiles is None:
+        raw_profiles = {}
+    if not isinstance(raw_profiles, dict):
+        raise ValidationError("`profiles` must be a table in config.toml")
+
+    profiles: dict[str, ProfileConfig] = {}
+    for profile_name, profile_data in raw_profiles.items():
+        if not isinstance(profile_name, str):
+            raise ValidationError("Profile names must be strings in config.toml")
+        if not isinstance(profile_data, dict):
+            raise ValidationError(f"Profile `{profile_name}` must be a table in config.toml")
+        profiles[profile_name] = ProfileConfig(
+            base_url=_as_optional_string(profile_data.get("base_url"), "base_url", profile_name),
+            api_key_env=_as_optional_string(
+                profile_data.get("api_key_env"),
+                "api_key_env",
+                profile_name,
+            ),
+            default_workspace=_as_optional_string(
+                profile_data.get("default_workspace"),
+                "default_workspace",
+                profile_name,
+            ),
+        )
+
+    raw_search_presets = raw.get("search_presets", {})
+    if raw_search_presets is None:
+        raw_search_presets = {}
+    if not isinstance(raw_search_presets, dict):
+        raise ValidationError("`search_presets` must be a table in config.toml")
+
+    search_presets: dict[str, SearchPresetConfig] = {}
+    for preset_name, preset_data in raw_search_presets.items():
+        if not isinstance(preset_name, str):
+            raise ValidationError("Search preset names must be strings in config.toml")
+        if not isinstance(preset_data, dict):
+            raise ValidationError(f"Search preset `{preset_name}` must be a table in config.toml")
+        kql = _as_required_string(preset_data.get("kql"), "kql", preset_name)
+        search_presets[preset_name] = SearchPresetConfig(
+            kql=kql,
+            scope=_as_optional_string(
+                preset_data.get("scope"),
+                "scope",
+                preset_name,
+                key_prefix="search_presets",
+            ),
+            default_format=_as_optional_string(
+                preset_data.get("default_format"),
+                "default_format",
+                preset_name,
+                key_prefix="search_presets",
+            ),
+        )
+
+    return AppConfig(
+        active_profile=active_profile,
+        profiles=profiles,
+        search_presets=search_presets,
+    )
+
+
+def _dump_app_config(config: AppConfig) -> str:
+    lines: list[str] = []
+
+    if config.active_profile is not None:
+        lines.append(f"active_profile = {_toml_quote(config.active_profile)}")
+
+    for profile_name in sorted(config.profiles):
+        profile = config.profiles[profile_name]
+        lines.append("")
+        lines.append(f"[profiles.{_toml_quote(profile_name)}]")
+        if profile.base_url is not None:
+            lines.append(f"base_url = {_toml_quote(profile.base_url)}")
+        if profile.api_key_env is not None:
+            lines.append(f"api_key_env = {_toml_quote(profile.api_key_env)}")
+        if profile.default_workspace is not None:
+            lines.append(f"default_workspace = {_toml_quote(profile.default_workspace)}")
+
+    for preset_name in sorted(config.search_presets):
+        preset = config.search_presets[preset_name]
+        lines.append("")
+        lines.append(f"[search_presets.{_toml_quote(preset_name)}]")
+        lines.append(f"kql = {_toml_quote(preset.kql)}")
+        if preset.scope is not None:
+            lines.append(f"scope = {_toml_quote(preset.scope)}")
+        if preset.default_format is not None:
+            lines.append(f"default_format = {_toml_quote(preset.default_format)}")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _as_optional_string(
+    value: Any,
+    key: str,
+    entry_name: str,
+    *,
+    key_prefix: str = "profiles",
+) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValidationError(f"`{key_prefix}.{entry_name}.{key}` must be a string in config.toml")
+    return value
+
+
+def _as_required_string(value: Any, key: str, entry_name: str) -> str:
+    if value is None:
+        raise ValidationError(f"`search_presets.{entry_name}.{key}` is required in config.toml")
+    if not isinstance(value, str):
+        raise ValidationError(
+            f"`search_presets.{entry_name}.{key}` must be a string in config.toml"
+        )
+    normalized = value.strip()
+    if not normalized:
+        raise ValidationError(
+            f"`search_presets.{entry_name}.{key}` must be a non-empty string in config.toml"
+        )
+    return normalized
+
+
+def _toml_quote(value: str) -> str:
+    return json.dumps(value)

kantree_cli/core/context.py

@@ -0,0 +1,141 @@
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from kantree_cli.core.config import (
+    DEFAULT_API_KEY_ENV,
+    DEFAULT_BASE_URL,
+    DEFAULT_PROFILE,
+    AppConfig,
+    config_path,
+    load_config,
+)
+
+
+@dataclass(slots=True)
+class ResolvedSettings:
+    profile_name: str
+    base_url: str
+    api_key_env: str
+    api_key_value: str | None
+    api_key_source: str
+    default_organization: str | None
+    default_organization_source: str | None
+    default_workspace: str | None
+    default_workspace_source: str | None
+
+
+@dataclass(slots=True)
+class AppRuntime:
+    config_path: Path
+    config: AppConfig
+    profile_override: str | None
+    base_url_override: str | None
+    organization_override: str | None
+    workspace_id_override: int | None
+    workspace_name_override: str | None
+    output_format: str
+    output_fields: list[str] | None
+    verbose: bool
+    assume_yes: bool
+    debug: bool
+
+    def resolve(self) -> ResolvedSettings:
+        profile_name = (
+            self.profile_override
+            or os.getenv("KANTREE_PROFILE")
+            or self.config.active_profile
+            or DEFAULT_PROFILE
+        )
+
+        profile_config = self.config.profiles.get(profile_name)
+
+        base_url = (
+            self.base_url_override
+            or os.getenv("KANTREE_BASE_URL")
+            or (profile_config.base_url if profile_config else None)
+            or DEFAULT_BASE_URL
+        )
+        base_url = base_url.rstrip("/")
+
+        api_key_env = (
+            os.getenv("KANTREE_API_KEY_ENV")
+            or (profile_config.api_key_env if profile_config else None)
+            or DEFAULT_API_KEY_ENV
+        )
+
+        direct_api_key = os.getenv("KANTREE_API_KEY")
+        if direct_api_key:
+            api_key_value = direct_api_key
+            api_key_source = "env:KANTREE_API_KEY"
+        else:
+            api_key_value = os.getenv(api_key_env)
+            api_key_source = f"env:{api_key_env}"
+
+        default_organization = self.organization_override
+        default_organization_source = (
+            "flag:--org" if self.organization_override is not None else None
+        )
+
+        default_workspace: str | None = None
+        default_workspace_source: str | None = None
+        env_workspace_id = (os.getenv("KANTREE_WORKSPACE_ID") or "").strip()
+        env_workspace_name = (os.getenv("KANTREE_WORKSPACE") or "").strip()
+        if env_workspace_id:
+            default_workspace = env_workspace_id
+            default_workspace_source = "env:KANTREE_WORKSPACE_ID"
+        elif env_workspace_name:
+            default_workspace = env_workspace_name
+            default_workspace_source = "env:KANTREE_WORKSPACE"
+        elif profile_config and profile_config.default_workspace:
+            default_workspace = profile_config.default_workspace.strip() or None
+            if default_workspace:
+                default_workspace_source = f"profile:{profile_name}.default_workspace"
+
+        if self.workspace_id_override is not None:
+            default_workspace = str(self.workspace_id_override)
+            default_workspace_source = "flag:--workspace-id"
+        elif self.workspace_name_override is not None:
+            default_workspace = self.workspace_name_override
+            default_workspace_source = "flag:--workspace"
+
+        return ResolvedSettings(
+            profile_name=profile_name,
+            base_url=base_url,
+            api_key_env=api_key_env,
+            api_key_value=api_key_value,
+            api_key_source=api_key_source,
+            default_organization=default_organization,
+            default_organization_source=default_organization_source,
+            default_workspace=default_workspace,
+            default_workspace_source=default_workspace_source,
+        )
+
+
+def build_runtime(
+    profile_override: str | None,
+    base_url_override: str | None,
+    organization_override: str | None,
+    workspace_id_override: int | None,
+    workspace_name_override: str | None,
+    output_format: str,
+    output_fields: list[str] | None,
+    verbose: bool,
+    assume_yes: bool,
+    debug: bool,
+) -> AppRuntime:
+    path = config_path()
+    return AppRuntime(
+        config_path=path,
+        config=load_config(path),
+        profile_override=profile_override,
+        base_url_override=base_url_override,
+        organization_override=organization_override,
+        workspace_id_override=workspace_id_override,
+        workspace_name_override=workspace_name_override,
+        output_format=output_format.lower(),
+        output_fields=output_fields,
+        verbose=verbose,
+        assume_yes=assume_yes,
+        debug=debug,
+    )

kantree_cli/core/errors.py

@@ -0,0 +1,32 @@
+class KantreeError(Exception):
+    """Base class for normalized CLI errors with explicit exit codes."""
+
+    exit_code = 1
+
+
+class AuthError(KantreeError):
+    exit_code = 3
+
+
+class NotFoundError(KantreeError):
+    exit_code = 4
+
+
+class AmbiguityError(KantreeError):
+    exit_code = 5
+
+
+class ValidationError(KantreeError):
+    exit_code = 6
+
+
+class ApiError(KantreeError):
+    exit_code = 7
+
+
+class NetworkError(KantreeError):
+    exit_code = 8
+
+
+class PreconditionError(KantreeError):
+    exit_code = 12

kantree_cli/core/output.py

@@ -0,0 +1,64 @@
+import json
+from typing import Any, Iterable
+
+import click
+
+
+def emit_json(payload: Any) -> None:
+    click.echo(json.dumps(payload, indent=2, ensure_ascii=False, sort_keys=True))
+
+
+def emit_ids(values: Iterable[object]) -> None:
+    for value in values:
+        click.echo(str(value))
+
+
+def emit_ndjson(values: Iterable[Any]) -> None:
+    for value in values:
+        click.echo(json.dumps(value, ensure_ascii=False, sort_keys=True))
+
+
+def value_for_field(item: dict[str, Any], field: str) -> Any:
+    current: Any = item
+    for token in field.split("."):
+        if not isinstance(current, dict):
+            return None
+        current = current.get(token)
+    return current
+
+
+def emit_tsv(items: list[dict[str, Any]], fields: list[str]) -> None:
+    click.echo("\t".join(fields))
+    for item in items:
+        row = [_stringify(value_for_field(item, field)) for field in fields]
+        click.echo("\t".join(row))
+
+
+def emit_table(items: list[dict[str, Any]], fields: list[str]) -> None:
+    rows = [[_stringify(value_for_field(item, field)) for field in fields] for item in items]
+    widths = [len(field) for field in fields]
+    for row in rows:
+        for index, cell in enumerate(row):
+            widths[index] = max(widths[index], len(cell))
+
+    header = " | ".join(field.ljust(widths[index]) for index, field in enumerate(fields))
+    separator = "-+-".join("-" * width for width in widths)
+    click.echo(header)
+    click.echo(separator)
+    for row in rows:
+        click.echo(" | ".join(cell.ljust(widths[index]) for index, cell in enumerate(row)))
+
+
+def _stringify(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float, str)):
+        return str(value)
+    return json.dumps(value, ensure_ascii=False, sort_keys=True)
+
+
+def emit_error(message: str, *, exit_code: int) -> None:
+    click.echo(f"Error: {message}", err=True)
+    raise click.exceptions.Exit(exit_code)