sv-cli 0.3.0__py3-none-any.whl

sv_cli/config.py

@@ -0,0 +1,216 @@
+"""Configuration, profiles, and API-key resolution."""
+
+from __future__ import annotations
+
+import getpass
+import os
+from pathlib import Path
+from typing import Any
+
+from .errors import AuthError, ConfigError
+from .utils import app_dir, legacy_app_dir, mask_mapping, read_json_file, write_json_file
+
+DEFAULT_BASE_URL = "https://ai.seovendor.co/api/"
+DEFAULT_CACHE_TTL_SECONDS = 24 * 60 * 60
+
+
+def config_path() -> Path:
+    return app_dir() / "config.json"
+
+
+def legacy_config_path() -> Path:
+    return legacy_app_dir() / "config.json"
+
+
+def default_config() -> dict[str, Any]:
+    return {
+        "default_profile": "default",
+        "profiles": {
+            "default": {
+                "api_key": None,
+                "base_url": DEFAULT_BASE_URL,
+            }
+        },
+        "defaults": {
+            "format": "pretty",
+            "cache_ttl_seconds": DEFAULT_CACHE_TTL_SECONDS,
+            "strict": False,
+            "fuzzy": True,
+        },
+    }
+
+
+def load_config() -> dict[str, Any]:
+    path = config_path()
+    if not path.exists():
+        # When a caller explicitly sets SV_HOME or SEOVENDOR_HOME, keep all
+        # reads isolated to that directory. Otherwise, read the legacy default
+        # path once as a migration aid for pre-rename installs.
+        if os.environ.get("SV_HOME") or os.environ.get("SEOVENDOR_HOME"):
+            return default_config()
+        legacy_path = legacy_config_path()
+        if legacy_path.exists():
+            path = legacy_path
+        else:
+            return default_config()
+    try:
+        loaded = read_json_file(path, default_config())
+    except ValueError as exc:
+        raise ConfigError(str(exc)) from exc
+    cfg = default_config()
+    cfg.update({k: v for k, v in loaded.items() if k != "profiles"})
+    cfg["profiles"].update(loaded.get("profiles", {}))
+    cfg.setdefault("defaults", {}).update(loaded.get("defaults", {}))
+    if cfg.get("default_profile") not in cfg.get("profiles", {}):
+        cfg["default_profile"] = "default"
+        cfg["profiles"].setdefault("default", {"api_key": None, "base_url": DEFAULT_BASE_URL})
+    return cfg
+
+
+def save_config(cfg: dict[str, Any]) -> None:
+    write_json_file(config_path(), cfg)
+
+
+def masked_config() -> dict[str, Any]:
+    return mask_mapping(load_config())
+
+
+def get_profile_name(cfg: dict[str, Any], profile: str | None = None) -> str:
+    return profile or cfg.get("default_profile") or "default"
+
+
+def get_profile(cfg: dict[str, Any], profile: str | None = None, create: bool = False) -> dict[str, Any]:
+    name = get_profile_name(cfg, profile)
+    profiles = cfg.setdefault("profiles", {})
+    if name not in profiles:
+        if not create:
+            raise ConfigError(f'Profile "{name}" does not exist. Create it with: sv profile create {name}')
+        profiles[name] = {"api_key": None, "base_url": DEFAULT_BASE_URL}
+    profiles[name].setdefault("base_url", DEFAULT_BASE_URL)
+    profiles[name].setdefault("api_key", None)
+    return profiles[name]
+
+
+def resolve_base_url(cli_base_url: str | None = None, profile: str | None = None) -> str:
+    if cli_base_url:
+        return normalize_base_url(cli_base_url)
+    cfg = load_config()
+    value = get_profile(cfg, profile).get("base_url") or DEFAULT_BASE_URL
+    return normalize_base_url(value)
+
+
+def normalize_base_url(base_url: str) -> str:
+    return base_url.rstrip("/") + "/"
+
+
+def resolve_api_key(
+    *,
+    cli_api_key: str | None = None,
+    profile: str | None = None,
+    allow_prompt: bool = False,
+    non_interactive: bool = False,
+) -> str:
+    if cli_api_key:
+        return cli_api_key
+    env_key = os.environ.get("SV_API_KEY") or os.environ.get("SEOVENDOR_API_KEY")
+    if env_key:
+        return env_key
+    cfg = load_config()
+    stored = get_profile(cfg, profile).get("api_key")
+    if stored:
+        return stored
+    if allow_prompt and not non_interactive:
+        entered = getpass.getpass("SV API key: ").strip()
+        if entered:
+            return entered
+    raise AuthError(
+        "Missing SV API key. Set SV_API_KEY, run `sv auth set`, "
+        "or pass --api-key. SEOVENDOR_API_KEY is also accepted as a legacy fallback. "
+        "Avoid --api-key in shared shells because it may be saved in history."
+    )
+
+
+def set_api_key(api_key: str, profile: str | None = None) -> None:
+    cfg = load_config()
+    prof = get_profile(cfg, profile, create=True)
+    prof["api_key"] = api_key
+    save_config(cfg)
+
+
+def clear_api_key(profile: str | None = None) -> None:
+    cfg = load_config()
+    prof = get_profile(cfg, profile, create=True)
+    prof["api_key"] = None
+    save_config(cfg)
+
+
+def set_profile_value(profile: str, key: str, value: Any) -> None:
+    cfg = load_config()
+    prof = get_profile(cfg, profile, create=True)
+    prof[key] = value
+    save_config(cfg)
+
+
+def create_profile(name: str, *, base_url: str | None = None, api_key: str | None = None) -> None:
+    cfg = load_config()
+    if name in cfg.setdefault("profiles", {}):
+        raise ConfigError(f'Profile "{name}" already exists.')
+    cfg["profiles"][name] = {
+        "api_key": api_key,
+        "base_url": normalize_base_url(base_url or DEFAULT_BASE_URL),
+    }
+    save_config(cfg)
+
+
+def delete_profile(name: str) -> None:
+    cfg = load_config()
+    if name == "default":
+        raise ConfigError('The "default" profile cannot be deleted.')
+    if name not in cfg.setdefault("profiles", {}):
+        raise ConfigError(f'Profile "{name}" does not exist.')
+    del cfg["profiles"][name]
+    if cfg.get("default_profile") == name:
+        cfg["default_profile"] = "default"
+    save_config(cfg)
+
+
+def use_profile(name: str) -> None:
+    cfg = load_config()
+    if name not in cfg.setdefault("profiles", {}):
+        raise ConfigError(f'Profile "{name}" does not exist. Create it with: sv profile create {name}')
+    cfg["default_profile"] = name
+    save_config(cfg)
+
+
+def set_config_value(key: str, value: Any, profile: str | None = None) -> None:
+    cfg = load_config()
+    if key == "base_url":
+        get_profile(cfg, profile, create=True)[key] = normalize_base_url(str(value))
+    elif key == "api_key":
+        get_profile(cfg, profile, create=True)[key] = str(value)
+    elif key == "default_profile":
+        if value not in cfg.get("profiles", {}):
+            raise ConfigError(f'Profile "{value}" does not exist.')
+        cfg["default_profile"] = str(value)
+    else:
+        cfg.setdefault("defaults", {})[key] = value
+    save_config(cfg)
+
+
+def get_config_value(key: str, profile: str | None = None) -> Any:
+    cfg = load_config()
+    if key in {"base_url", "api_key"}:
+        value = get_profile(cfg, profile).get(key)
+    elif key == "default_profile":
+        value = cfg.get("default_profile")
+    else:
+        value = cfg.setdefault("defaults", {}).get(key)
+    if key == "api_key" and value:
+        return "***masked***" + str(value)[-4:]
+    return value
+
+
+def reset_config() -> None:
+    path = config_path()
+    if path.exists():
+        path.unlink()

sv_cli/definitions.py

@@ -0,0 +1,283 @@
+"""Dynamic SV API discovery and local definitions cache."""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import time
+from pathlib import Path
+from typing import Any
+from urllib.parse import urljoin
+
+import httpx
+
+from .adapters import TOOL_ADAPTERS, all_command_names, tool_display_name
+from .config import DEFAULT_BASE_URL, load_config, normalize_base_url
+from .errors import ConfigError, NetworkError
+from .utils import app_dir, normalize_text, read_json_file, write_json_file
+
+CACHE_VERSION = 1
+
+
+def cache_path() -> Path:
+    return app_dir() / "cache" / "definitions.json"
+
+
+def utc_now() -> str:
+    return dt.datetime.now(dt.timezone.utc).isoformat()
+
+
+def parse_timestamp(value: str | None) -> float:
+    if not value:
+        return 0.0
+    try:
+        return dt.datetime.fromisoformat(value).timestamp()
+    except ValueError:
+        return 0.0
+
+
+def default_cache(base_url: str = DEFAULT_BASE_URL) -> dict[str, Any]:
+    return {
+        "version": CACHE_VERSION,
+        "base_url": normalize_base_url(base_url),
+        "fetched_at": None,
+        "root": {},
+        "tools": {},
+        "warnings": [],
+    }
+
+
+class DefinitionsManager:
+    """Fetch, cache, and resolve API root/tool definitions."""
+
+    def __init__(self, base_url: str | None = None, *, ttl_seconds: int | None = None) -> None:
+        cfg = load_config()
+        profile_name = cfg.get("default_profile") or "default"
+        profile = cfg.get("profiles", {}).get(profile_name, {})
+        self.base_url = normalize_base_url(base_url or profile.get("base_url") or DEFAULT_BASE_URL)
+        self.ttl_seconds = int(
+            ttl_seconds
+            if ttl_seconds is not None
+            else cfg.get("defaults", {}).get("cache_ttl_seconds", 24 * 60 * 60)
+        )
+        self.path = cache_path()
+
+    def load_cache(self) -> dict[str, Any]:
+        try:
+            cached = read_json_file(self.path, default_cache(self.base_url))
+        except ValueError as exc:
+            raise ConfigError(str(exc)) from exc
+        if not cached:
+            return default_cache(self.base_url)
+        cached.setdefault("version", CACHE_VERSION)
+        cached.setdefault("base_url", self.base_url)
+        cached.setdefault("root", {})
+        cached.setdefault("tools", {})
+        cached.setdefault("warnings", [])
+        self.ensure_supplemental_tools(cached)
+        return cached
+
+    def save_cache(self, cache: dict[str, Any]) -> None:
+        cache["version"] = CACHE_VERSION
+        cache["base_url"] = self.base_url
+        write_json_file(self.path, cache)
+
+    def clear_cache(self) -> bool:
+        if self.path.exists():
+            self.path.unlink()
+            return True
+        return False
+
+    def is_stale(self, cache: dict[str, Any]) -> bool:
+        if not cache.get("root"):
+            return True
+        fetched = parse_timestamp(cache.get("fetched_at"))
+        return (time.time() - fetched) > self.ttl_seconds
+
+    def get_cache(self, *, refresh: bool = False, allow_stale: bool = True) -> dict[str, Any]:
+        cache = self.load_cache()
+        if refresh or self.is_stale(cache):
+            try:
+                return self.refresh_all()
+            except Exception as exc:  # noqa: BLE001 - cache fallback should be broad
+                if allow_stale and cache.get("root"):
+                    cache.setdefault("warnings", []).append(
+                        f"Definitions refresh failed; using stale cache: {exc}"
+                    )
+                    return cache
+                if isinstance(exc, NetworkError):
+                    raise
+                raise NetworkError(f"Could not fetch API definitions and no usable cache exists: {exc}") from exc
+        return cache
+
+    def fetch_json(self, url: str) -> Any:
+        try:
+            with httpx.Client(timeout=30.0, follow_redirects=True) as client:
+                response = client.get(url)
+                response.raise_for_status()
+                return response.json()
+        except httpx.TimeoutException as exc:
+            raise NetworkError(f"Timed out while fetching {url}") from exc
+        except httpx.HTTPStatusError as exc:
+            raise NetworkError(
+                f"Definitions request failed for {url}: HTTP {exc.response.status_code}"
+            ) from exc
+        except httpx.RequestError as exc:
+            raise NetworkError(f"Network error while fetching {url}: {exc}") from exc
+        except json.JSONDecodeError as exc:
+            raise NetworkError(f"Definitions endpoint did not return valid JSON: {url}") from exc
+
+    def supplemental_root_entries(self) -> dict[str, dict[str, str]]:
+        """Return adapter-provided endpoint hints for tools missing from the API root.
+
+        These entries are a compatibility bridge for newly released tools whose
+        definitions endpoints are live before the API root advertises them.
+        They are deliberately derived from the active base URL, so profiles and
+        staging URLs still work.
+        """
+
+        entries: dict[str, dict[str, str]] = {}
+        for canonical, adapter in TOOL_ADAPTERS.items():
+            if not adapter.endpoint_path:
+                continue
+            definitions_path = adapter.definitions_path or f"{adapter.endpoint_path.rstrip('/')}/definitions"
+            entries[canonical] = {
+                "Endpoint": join_base_url(self.base_url, adapter.endpoint_path),
+                "Definitions": join_base_url(self.base_url, definitions_path),
+                "Source": "local-adapter-fallback",
+            }
+        return entries
+
+    def ensure_supplemental_tools(self, cache: dict[str, Any]) -> None:
+        """Merge local adapter hints into a cache without overwriting live root data."""
+
+        root = cache.setdefault("root", {})
+        tools = cache.setdefault("tools", {})
+        for tool_name, meta in self.supplemental_root_entries().items():
+            if tool_name in root:
+                continue
+            root[tool_name] = meta
+            tools.setdefault(
+                tool_name,
+                {
+                    "tool": tool_name,
+                    "display_name": tool_display_name(tool_name),
+                    "endpoint": meta.get("Endpoint"),
+                    "definitions_url": meta.get("Definitions"),
+                    "definition": None,
+                    "last_fetched": None,
+                    "source": meta.get("Source"),
+                },
+            )
+
+    def refresh_all(self) -> dict[str, Any]:
+        root = self.fetch_json(self.base_url)
+        if not isinstance(root, dict):
+            raise NetworkError(f"API root {self.base_url} did not return a JSON object")
+        cache = default_cache(self.base_url)
+        cache["root"] = dict(root)
+        self.ensure_supplemental_tools(cache)
+        cache["fetched_at"] = utc_now()
+        warnings: list[str] = []
+        for tool_name, meta in cache["root"].items():
+            endpoint = _pick_value(meta, "Endpoint", "endpoint", "url")
+            definitions_url = _pick_value(meta, "Definitions", "definitions", "definition", "schema")
+            existing_entry = cache.get("tools", {}).get(tool_name, {})
+            tool_entry = {
+                "tool": tool_name,
+                "display_name": tool_display_name(tool_name),
+                "endpoint": endpoint or existing_entry.get("endpoint"),
+                "definitions_url": definitions_url or existing_entry.get("definitions_url"),
+                "definition": existing_entry.get("definition"),
+                "last_fetched": existing_entry.get("last_fetched"),
+                "source": existing_entry.get("source", "api-root"),
+            }
+            if tool_entry.get("definitions_url"):
+                try:
+                    tool_entry["definition"] = self.fetch_json(str(tool_entry["definitions_url"]))
+                    tool_entry["last_fetched"] = utc_now()
+                except Exception as exc:  # noqa: BLE001 - partial cache is still useful
+                    warnings.append(f"Could not fetch definitions for {tool_name}: {exc}")
+            cache["tools"][tool_name] = tool_entry
+        cache["warnings"] = warnings
+        self.save_cache(cache)
+        return cache
+
+    def refresh_tool(self, tool_name: str) -> dict[str, Any]:
+        cache = self.get_cache(allow_stale=True)
+        canonical = self.resolve_tool(tool_name, cache)
+        entry = cache.get("tools", {}).get(canonical)
+        if not entry:
+            raise ConfigError(f'Tool "{tool_name}" is not available in the API root.')
+        definitions_url = entry.get("definitions_url")
+        if not definitions_url:
+            raise NetworkError(f'Tool "{canonical}" does not expose a definitions URL in the root.')
+        entry["definition"] = self.fetch_json(str(definitions_url))
+        entry["last_fetched"] = utc_now()
+        cache["tools"][canonical] = entry
+        self.save_cache(cache)
+        return entry
+
+    def resolve_tool(self, user_value: str, cache: dict[str, Any] | None = None) -> str:
+        cache = cache or self.get_cache(allow_stale=True)
+        root_tools = set(cache.get("root", {}).keys()) | set(cache.get("tools", {}).keys())
+        if user_value in root_tools:
+            return user_value
+        alias_map = all_command_names()
+        if user_value in alias_map:
+            preferred = alias_map[user_value]
+            if preferred in root_tools:
+                return preferred
+        norm_user = normalize_text(user_value).replace(" ", "")
+        for name in root_tools:
+            if normalize_text(name).replace(" ", "") == norm_user:
+                return name
+        for alias, canonical in alias_map.items():
+            if normalize_text(alias).replace(" ", "") == norm_user and canonical in root_tools:
+                return canonical
+        known = ", ".join(sorted(root_tools)) or "none"
+        raise ConfigError(f'Unknown tool "{user_value}". Available tools: {known}')
+
+    def get_tool(self, user_value: str, *, refresh: bool = False) -> dict[str, Any]:
+        cache = self.get_cache(refresh=refresh, allow_stale=True)
+        canonical = self.resolve_tool(user_value, cache)
+        entry = cache.get("tools", {}).get(canonical)
+        if entry:
+            if entry.get("definition") is None and entry.get("definitions_url"):
+                try:
+                    entry["definition"] = self.fetch_json(str(entry["definitions_url"]))
+                    entry["last_fetched"] = utc_now()
+                    cache.setdefault("tools", {})[canonical] = entry
+                    self.save_cache(cache)
+                except Exception as exc:  # noqa: BLE001 - callers can still use raw or schema-light tools
+                    entry["definition_warning"] = f"Could not fetch definitions: {exc}"
+            return entry
+        meta = cache.get("root", {}).get(canonical, {})
+        entry = {
+            "tool": canonical,
+            "display_name": tool_display_name(canonical),
+            "endpoint": _pick_value(meta, "Endpoint", "endpoint", "url"),
+            "definitions_url": _pick_value(meta, "Definitions", "definitions", "definition", "schema"),
+            "definition": None,
+            "last_fetched": None,
+        }
+        cache.setdefault("tools", {})[canonical] = entry
+        self.save_cache(cache)
+        return entry
+
+
+def join_base_url(base_url: str, path: str) -> str:
+    return urljoin(normalize_base_url(base_url), path.lstrip("/"))
+
+
+def _pick_value(data: Any, *keys: str) -> Any:
+    if not isinstance(data, dict):
+        return None
+    for key in keys:
+        if key in data:
+            return data[key]
+    lowered = {str(k).lower(): v for k, v in data.items()}
+    for key in keys:
+        if key.lower() in lowered:
+            return lowered[key.lower()]
+    return None

sv_cli/errors.py

@@ -0,0 +1,55 @@
+"""Typed exceptions and exit-code helpers for SV CLI."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class CLIError(Exception):
+    """Base error carrying a process exit code."""
+
+    message: str
+    exit_code: int = 1
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.message
+
+
+class InvalidInputError(CLIError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, 2)
+
+
+class AmbiguousMatchError(InvalidInputError):
+    pass
+
+
+class AuthError(CLIError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, 3)
+
+
+class APIError(CLIError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, 4)
+
+
+class NetworkError(CLIError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, 5)
+
+
+class TimeoutError(CLIError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, 6)
+
+
+class ConfigError(CLIError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, 7)
+
+
+class UnsupportedFeatureError(CLIError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, 8)