lovarch-cli 0.2.1__py3-none-any.whl

lovarch_cli/config_store.py

@@ -0,0 +1,111 @@
+"""User config store — ~/.lovarch/config.json.
+
+Holds non-secret preferences (language, storage path) and, for FREE mode, the
+student's own provider API keys (OpenAI, Mapbox) so `lovarch run` in free mode
+can pick them up without exporting shell env vars. Premium mode never needs
+these — paid AI is debited via the platform.
+
+Secret values are stored chmod 0600 and masked when displayed.
+"""
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+from typing import Any
+
+from lovarch_cli.config import DEFAULT_HOME
+
+# Allowed keys and whether each is secret (masked on display).
+CONFIG_KEYS: dict[str, bool] = {
+    "language": False,      # it | en | pt | es
+    "storage_path": False,  # where free-mode projects live (default ~/.lovarch/projects)
+    "openai_key": True,     # BYO key for free mode
+    "mapbox_token": True,   # BYO token for free mode (geocoding)
+}
+
+_VALID_LANGS = {"it", "en", "pt", "es"}
+
+
+class ConfigError(Exception):
+    """Invalid config key or value."""
+
+
+def config_path(home: Path | None = None) -> Path:
+    return (home or DEFAULT_HOME) / "config.json"
+
+
+def load_config(home: Path | None = None) -> dict[str, Any]:
+    path = config_path(home)
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text())
+        return data if isinstance(data, dict) else {}
+    except (json.JSONDecodeError, ValueError, OSError):
+        return {}
+
+
+def _save_config(data: dict[str, Any], home: Path | None = None) -> Path:
+    path = config_path(home)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+    # Config may hold BYO API keys → keep it private.
+    try:
+        os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)  # 0600
+    except OSError:
+        pass
+    return path
+
+
+def _validate(key: str, value: str) -> str:
+    if key not in CONFIG_KEYS:
+        raise ConfigError(
+            f"Chiave sconosciuta: '{key}'. Valide: {', '.join(sorted(CONFIG_KEYS))}."
+        )
+    if key == "language" and value not in _VALID_LANGS:
+        raise ConfigError(f"Lingua non valida: '{value}'. Valide: it, en, pt, es.")
+    if not value:
+        raise ConfigError("Il valore non può essere vuoto (usa `unset` per rimuovere).")
+    return value
+
+
+def set_value(key: str, value: str, home: Path | None = None) -> None:
+    value = _validate(key, value)
+    data = load_config(home)
+    data[key] = value
+    _save_config(data, home)
+
+
+def get_value(key: str, home: Path | None = None) -> Any:
+    if key not in CONFIG_KEYS:
+        raise ConfigError(f"Chiave sconosciuta: '{key}'.")
+    return load_config(home).get(key)
+
+
+def unset_value(key: str, home: Path | None = None) -> bool:
+    if key not in CONFIG_KEYS:
+        raise ConfigError(f"Chiave sconosciuta: '{key}'.")
+    data = load_config(home)
+    if key in data:
+        del data[key]
+        _save_config(data, home)
+        return True
+    return False
+
+
+def mask(key: str, value: Any) -> str:
+    """Mask secret values for display (show only the last 4 chars)."""
+    if value is None:
+        return "—"
+    text = str(value)
+    if CONFIG_KEYS.get(key) and len(text) > 4:
+        return "•" * (len(text) - 4) + text[-4:]
+    return text
+
+
+def display_items(home: Path | None = None) -> list[tuple[str, str, bool]]:
+    """Return (key, masked_value, is_secret) for every known key."""
+    data = load_config(home)
+    return [(k, mask(k, data.get(k)), CONFIG_KEYS[k]) for k in CONFIG_KEYS]

lovarch_cli/credits/__init__.py

@@ -0,0 +1,35 @@
+"""Credits — pre-flight balance check for Premium pipelines.
+
+Free mode users bring their own API keys (OpenAI, Mapbox, etc.) — they pay
+their providers directly, so the CLI never debits credits. The Free client
+is a no-op that always returns an "unlimited" balance.
+
+Premium users pay via Lovarch credits. Before starting a long pipeline
+(`arch run dal-brief-al-cantiere` consumes ~3,500 credits typical), we hit
+the `cli-credits-check` Edge Function to verify the user has enough headroom
+and abort EARLY with a clear message rather than failing mid-pipeline.
+
+Usage:
+    from lovarch_cli.credits import (
+        InsufficientCreditsError,
+        get_credits_client,
+    )
+
+    client = get_credits_client(mode)
+    balance = await client.check(required=3500)
+    if not balance.sufficient:
+        raise InsufficientCreditsError(balance)
+"""
+from lovarch_cli.credits.base import (
+    CreditsBalance,
+    CreditsClient,
+    InsufficientCreditsError,
+)
+from lovarch_cli.credits.factory import get_credits_client
+
+__all__ = [
+    "CreditsBalance",
+    "CreditsClient",
+    "InsufficientCreditsError",
+    "get_credits_client",
+]

lovarch_cli/credits/base.py

@@ -0,0 +1,84 @@
+"""Credits — abstract base + value types."""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CreditsBalance:
+    """Snapshot of a user's credit standing at a point in time.
+
+    Attributes:
+        balance: total credits granted (monthly + bonus).
+        monthly_used: credits consumed since the start of the cycle.
+        credits_remaining: max(0, balance - monthly_used).
+        is_admin: admins bypass credit gates entirely.
+        required: threshold the caller asked us to compare against, or None.
+        sufficient: is_admin OR credits_remaining >= required (True when
+            required is None — i.e. caller just wants the balance).
+    """
+
+    balance: int
+    monthly_used: int
+    credits_remaining: int
+    is_admin: bool
+    required: int | None
+    sufficient: bool
+
+    @property
+    def deficit(self) -> int:
+        """How many extra credits the user needs to cross `required`.
+
+        Returns 0 when sufficient or when no required threshold was given.
+        """
+        if self.sufficient or self.required is None:
+            return 0
+        return max(0, self.required - self.credits_remaining)
+
+
+class InsufficientCreditsError(Exception):
+    """Raised when a pipeline cannot proceed because of credit shortage.
+
+    Carries the full balance so callers can render rich error UI.
+    """
+
+    def __init__(self, balance: CreditsBalance) -> None:
+        self.balance = balance
+        super().__init__(
+            f"Insufficient credits: have {balance.credits_remaining}, "
+            f"need {balance.required} (deficit: {balance.deficit})"
+        )
+
+
+class CreditsClient(ABC):
+    """Backend-agnostic credits interface.
+
+    Free mode returns an unlimited no-op; Premium calls cli-credits-check.
+    """
+
+    @abstractmethod
+    async def check(self, required: int | None = None) -> CreditsBalance:
+        """Fetch the user's current balance.
+
+        Args:
+            required: if given, server compares and sets `sufficient`.
+
+        Returns:
+            CreditsBalance snapshot.
+
+        Raises:
+            RuntimeError: backend communication failure.
+        """
+        raise NotImplementedError
+
+    async def check_or_raise(self, required: int) -> CreditsBalance:
+        """Fetch balance and raise InsufficientCreditsError if not sufficient.
+
+        Convenience wrapper around `check()` for callers that just want to
+        gate an operation.
+        """
+        balance = await self.check(required=required)
+        if not balance.sufficient:
+            raise InsufficientCreditsError(balance)
+        return balance

lovarch_cli/credits/factory.py

@@ -0,0 +1,36 @@
+"""Credits — backend factory."""
+from __future__ import annotations
+
+from lovarch_cli.clients.persistence import ExecutionMode
+from lovarch_cli.credits.base import CreditsClient
+from lovarch_cli.credits.local import FreeCreditsClient
+
+
+def get_credits_client(mode: ExecutionMode) -> CreditsClient:
+    """Return the credits client matching the execution mode.
+
+    Free mode returns a no-op client (always sufficient).
+    Premium mode loads the keyring session and returns LovarchCreditsClient.
+
+    Raises:
+        RuntimeError: premium requested but no session in keyring.
+    """
+    if mode == ExecutionMode.FREE:
+        return FreeCreditsClient()
+
+    if mode == ExecutionMode.PREMIUM:
+        # Lazy imports — Free flows shouldn't pay for httpx + Supabase modules.
+        from lovarch_cli.auth.session import LovarchSession
+        from lovarch_cli.credits.lovarch import LovarchCreditsClient
+
+        session = LovarchSession.load()
+        if session is None:
+            msg = (
+                "Premium credits check requires authentication. Run "
+                "'lovarch login --premium' first."
+            )
+            raise RuntimeError(msg)
+        return LovarchCreditsClient(session)
+
+    msg = f"Unknown execution mode: {mode}"
+    raise ValueError(msg)

lovarch_cli/credits/local.py

@@ -0,0 +1,34 @@
+"""Credits — Free mode no-op implementation.
+
+Free users bring their own API keys; the CLI never debits Lovarch credits.
+This client always reports an unlimited balance with `sufficient=True`.
+
+Kept separate from base.py so the abstract module stays import-light and
+free users don't accidentally pay the cost of importing httpx.
+"""
+from __future__ import annotations
+
+from lovarch_cli.credits.base import CreditsBalance, CreditsClient
+
+# Sentinel used as the "unlimited" balance value. Picked arbitrarily large
+# (2^31 - 1) so any reasonable required threshold passes the check.
+_UNLIMITED = 2_147_483_647
+
+
+class FreeCreditsClient(CreditsClient):
+    """No-op client — always reports unlimited credits.
+
+    Free users supply their own provider keys (OpenAI, Mapbox), so the CLI
+    has no balance to track. We still return a CreditsBalance shape so
+    callers don't need to special-case Free vs Premium.
+    """
+
+    async def check(self, required: int | None = None) -> CreditsBalance:
+        return CreditsBalance(
+            balance=_UNLIMITED,
+            monthly_used=0,
+            credits_remaining=_UNLIMITED,
+            is_admin=False,
+            required=required,
+            sufficient=True,
+        )

lovarch_cli/credits/lovarch.py

@@ -0,0 +1,56 @@
+"""Credits — Premium mode implementation backed by cli-credits-check EF."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from lovarch_cli.credits.base import CreditsBalance, CreditsClient
+
+if TYPE_CHECKING:
+    from lovarch_cli.auth.session import LovarchSession
+
+
+class LovarchCreditsClient(CreditsClient):
+    """Calls the `cli-credits-check` Edge Function with the premium Bearer.
+
+    Uses LovarchSession's auto-refresh-on-401 request method, so a near-
+    expired access_token is handled transparently.
+    """
+
+    def __init__(self, session: "LovarchSession") -> None:
+        self._session = session
+
+    async def check(self, required: int | None = None) -> CreditsBalance:
+        body: dict[str, int] = {}
+        if required is not None:
+            body["required"] = int(required)
+
+        # session.request normalizes URL + injects Bearer + handles 401 refresh.
+        # cli-credits-check is at /functions/v1/cli-credits-check.
+        path = "/functions/v1/cli-credits-check"
+        response = await self._session.request("POST", path, json=body)
+
+        if response.status_code != 200:
+            # Try to surface server-localized message when present.
+            try:
+                payload = response.json()
+            except ValueError:
+                payload = {}
+            msg = payload.get("message") or response.text[:200]
+            raise RuntimeError(
+                f"cli-credits-check failed (HTTP {response.status_code}): {msg}"
+            )
+
+        data = response.json()
+        if data.get("ok") is not True:
+            raise RuntimeError(
+                f"cli-credits-check error: {data.get('error', 'unknown')}"
+            )
+
+        return CreditsBalance(
+            balance=int(data.get("balance", 0)),
+            monthly_used=int(data.get("monthly_used", 0)),
+            credits_remaining=int(data.get("credits_remaining", 0)),
+            is_admin=bool(data.get("is_admin", False)),
+            required=data.get("required"),
+            sufficient=bool(data.get("sufficient", False)),
+        )

lovarch_cli/i18n/__init__.py

@@ -0,0 +1,27 @@
+"""lovarch-cli i18n — bundled translations + lookup loader.
+
+4 languages supported (CLAUDE.md MANDATORY: 4 langs always):
+- it (Italiano) — DEFAULT
+- pt (Português)
+- en (English)
+- es (Español)
+
+Usage in subcommands:
+
+    from lovarch_cli.i18n import t, current_lang
+
+    print(t("signup.welcome_title"))
+    print(t("signup.invalid_email", lang="pt"))
+
+Detection chain (in current_lang()):
+  1. Explicit override via set_current_lang(...) (set by --lang flag in cli.py)
+  2. LOVARCH_LANG env var
+  3. LANG env var (e.g. 'it_IT.UTF-8' → 'it')
+  4. Default: 'it'
+
+Fallback chain on missing key:
+  requested_lang → 'it' → 'en' → key itself (returned as-is for visibility)
+"""
+from lovarch_cli.i18n.loader import current_lang, set_current_lang, t
+
+__all__ = ["t", "current_lang", "set_current_lang"]

lovarch_cli/i18n/loader.py

@@ -0,0 +1,121 @@
+"""i18n string loader — reads bundled JSON translations and provides t()."""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+log = logging.getLogger("lovarch_cli.i18n")
+
+VALID_LANGUAGES: tuple[str, ...] = ("it", "pt", "en", "es")
+DEFAULT_LANGUAGE = "it"
+FALLBACK_CHAIN = ("it", "en")  # tried in order if key missing in requested lang
+
+_TRANSLATIONS_DIR = Path(__file__).parent / "translations"
+
+# Module-level mutable holder for the active language. Set by cli.py at
+# startup via set_current_lang() based on the --lang flag.
+_current_lang: str | None = None
+
+
+@lru_cache(maxsize=4)
+def _load_translations(lang: str) -> dict[str, Any]:
+    """Load a translations JSON from bundled package data."""
+    path = _TRANSLATIONS_DIR / f"{lang}.json"
+    if not path.exists():
+        log.warning("i18n: translations file missing: %s", path)
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        log.warning("i18n: failed to load %s: %s", path, exc)
+        return {}
+
+
+def _detect_from_env() -> str:
+    """Detect language from environment variables only."""
+    arch_lang = os.environ.get("LOVARCH_LANG", "").lower().strip()
+    if arch_lang in VALID_LANGUAGES:
+        return arch_lang
+    sys_lang = os.environ.get("LANG", "").split("_")[0].lower()
+    if sys_lang in VALID_LANGUAGES:
+        return sys_lang
+    return DEFAULT_LANGUAGE
+
+
+def current_lang() -> str:
+    """Return the active language for translation lookups."""
+    global _current_lang
+    if _current_lang is None:
+        _current_lang = _detect_from_env()
+    return _current_lang
+
+
+def set_current_lang(lang: str | None) -> str:
+    """Override the active language (used by --lang flag at CLI start).
+
+    Pass None to reset to env-based detection on next current_lang() call.
+    Returns the resolved language (after validation/normalization).
+    """
+    global _current_lang
+    if lang is None:
+        _current_lang = None
+        return current_lang()
+    normalized = lang.lower().strip()
+    if normalized not in VALID_LANGUAGES:
+        log.warning(
+            "i18n: invalid lang override %r — falling back to env detection",
+            lang,
+        )
+        _current_lang = None
+        return current_lang()
+    _current_lang = normalized
+    return normalized
+
+
+def _lookup(key: str, lang: str) -> str | None:
+    """Walk dotted key (e.g. 'signup.welcome_title') in nested dict."""
+    data = _load_translations(lang)
+    parts = key.split(".")
+    node: Any = data
+    for part in parts:
+        if not isinstance(node, dict) or part not in node:
+            return None
+        node = node[part]
+    if isinstance(node, str):
+        return node
+    return None
+
+
+def t(key: str, lang: str | None = None, **vars: Any) -> str:
+    """Translate a key to the target language with fallback chain.
+
+    Args:
+        key: dotted key path (e.g. 'signup.welcome_title')
+        lang: optional override; defaults to current_lang()
+        vars: optional Python-format vars (e.g. t('cli.greet', name='Pablo'))
+
+    Returns:
+        Translated string, or the key itself if missing in all fallback langs
+        (so the developer can spot missing translations visually).
+    """
+    target = lang or current_lang()
+    chain = (target, *(L for L in FALLBACK_CHAIN if L != target))
+    value: str | None = None
+    for candidate in chain:
+        value = _lookup(key, candidate)
+        if value is not None:
+            break
+    if value is None:
+        log.warning("i18n: missing key %r in all langs %s", key, chain)
+        return key
+    if vars:
+        try:
+            return value.format(**vars)
+        except (KeyError, IndexError) as exc:
+            log.warning("i18n: format error for key %r vars %r: %s", key, vars, exc)
+            return value
+    return value