vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/lib/config/config.py

@@ -0,0 +1,141 @@
+"""Reads and atomically writes the versioned non-secret CLI configuration document.
+
+Native state wins over legacy state, and neither is ever repaired in place: a document the
+CLI cannot validate is reported, not overwritten, because a parse failure is far more often
+a bug or a partial write than a file the user wanted destroyed.
+
+Writes are read-modify-write, so `save` compares a digest of the file it is about to replace
+against the one the caller read. Two shells running `config set` at once is rare, but the
+losing write would silently discard the other's setting, and the check costs one read.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from ..errors.failures import (
+    ConfigInvalidBeforeWrite,
+    ConfigUnreadable,
+    ConfigWriteConflict,
+    InvalidConfigValue,
+)
+from .atomic import AtomicFileWriter
+from .models import DEFAULT_PROFILE, ConfigDocument, ConfigField, ProfileConfig
+from .paths import VidbytePaths
+
+# Configuration is a handful of scalars; anything this large is a wrong or hostile file, and
+# the bound keeps it from being read into memory before validation can reject it.
+_MAX_CONFIG_BYTES = 1_000_000
+
+
+@dataclass(frozen=True)
+class ConfigSnapshot:
+    """One validated document plus concurrency and provenance metadata."""
+
+    document: ConfigDocument
+    path: Path | None
+    digest: str | None
+    legacy: bool = False
+
+
+class ConfigStore:
+    """Typed local store for non-secret profile configuration."""
+
+    def __init__(
+        self,
+        paths: VidbytePaths | None = None,
+        writer: AtomicFileWriter | None = None,
+    ) -> None:
+        self.paths = paths or VidbytePaths.default()
+        self._writer = writer or AtomicFileWriter()
+
+    def load(self) -> ConfigSnapshot:
+        # Native state wins. Legacy state stays a compatible read until migration runs, so a
+        # user who never logs in again keeps their settings.
+        native = self.paths.config_file()
+        if native.exists():
+            return self._read(native, legacy=False)
+        legacy = self.paths.legacy_config_file()
+        if legacy.exists():
+            return self._read(legacy, legacy=True)
+        return ConfigSnapshot(ConfigDocument(), None, None)
+
+    def get(self, field: ConfigField, profile: str = DEFAULT_PROFILE) -> object:
+        snapshot = self.load()
+        return getattr(self._select_profile(snapshot.document, profile), field.value)
+
+    def set(self, field: ConfigField, value: str, profile: str = DEFAULT_PROFILE) -> ProfileConfig:
+        snapshot = self.load()
+        document = snapshot.document
+        updated = self._updated_profile(self._select_profile(document, profile), field, value)
+        profiles = dict(document.profiles)
+        profiles[profile] = updated
+        active_profile = document.active_profile if document.profiles else profile
+        saved = ConfigDocument(active_profile=active_profile, profiles=profiles)
+        # The digest of the native file, not the snapshot's: a legacy read has no native
+        # file yet, and this write is what creates it.
+        self.save(saved, expected_digest=self._native_digest())
+        return updated
+
+    def save(self, document: ConfigDocument, *, expected_digest: str | None = None) -> None:
+        if self._native_digest() != expected_digest:
+            raise ConfigWriteConflict()
+        encoded = document.model_dump_json(indent=2).encode("utf-8") + b"\n"
+        self._writer.write(self.paths.config_file(), encoded)
+
+    def _read(self, path: Path, *, legacy: bool) -> ConfigSnapshot:
+        try:
+            raw = path.read_bytes()
+            if len(raw) > _MAX_CONFIG_BYTES:
+                raise ValueError("configuration exceeds the size limit")
+            parsed = json.loads(raw)
+            # Checked before validation so a future document reports its version rather than
+            # a list of fields this release happens not to know.
+            if isinstance(parsed, dict) and parsed.get("schema_version", 1) != 1:
+                raise ValueError("unsupported configuration schema")
+            document = ConfigDocument.model_validate(parsed)
+        except (OSError, UnicodeError, json.JSONDecodeError, ValidationError, ValueError) as error:
+            raise ConfigUnreadable(str(path), error) from error
+        return ConfigSnapshot(document, path, hashlib.sha256(raw).hexdigest(), legacy)
+
+    def _select_profile(self, document: ConfigDocument, profile: str) -> ProfileConfig:
+        # An unknown profile falls back rather than failing: a profile may exist only as a
+        # credential scope, with no stored settings of its own.
+        selected = document.profiles.get(profile)
+        if selected is not None:
+            return selected
+        return document.profiles.get(DEFAULT_PROFILE, ProfileConfig())
+
+    def _updated_profile(
+        self,
+        current: ProfileConfig,
+        field: ConfigField,
+        value: str,
+    ) -> ProfileConfig:
+        # Revalidating the whole profile keeps one validation path for command, environment,
+        # and persisted values, so `config set` cannot write what `load` would reject.
+        values = current.model_dump()
+        values[field.value] = value
+        try:
+            return ProfileConfig.model_validate(values)
+        except ValidationError as error:
+            raise InvalidConfigValue(field.value, error) from error
+
+    def _native_digest(self) -> str | None:
+        path = self.paths.config_file()
+        if not path.exists():
+            return None
+        try:
+            raw = path.read_bytes()
+            parsed = json.loads(raw)
+            if not isinstance(parsed, dict) or parsed.get("schema_version", 1) != 1:
+                raise ValueError("unsupported configuration schema")
+            ConfigDocument.model_validate(parsed)
+        except (OSError, json.JSONDecodeError, ValidationError, ValueError) as error:
+            raise ConfigInvalidBeforeWrite(str(path), error) from error
+        return hashlib.sha256(raw).hexdigest()

vidbyte_cli/lib/config/migration.py

@@ -0,0 +1,81 @@
+"""Copies compatible `~/.vidbyte` state into the platform-native locations, and verifies it.
+
+Two properties make this safe to run from any mutating command. It never deletes: the legacy
+tree is left exactly as it was, so a user who downgrades still has working state. And it is
+destination-preserving and idempotent: an existing native file always wins, so running it
+twice does nothing the first run did not already do.
+
+Every copy is read back and compared before it counts as migrated. A credential in
+particular is only migrated once the keyring returns the same secret that was written.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from pydantic import ValidationError
+
+from ..auth.credentials import Credentials
+from ..auth.keyring_store import KeyringCredentialStore
+from ..errors.failures import LegacyCredentialUnreadable, MigrationVerificationFailed
+from .config import ConfigStore
+from .models import DEFAULT_API_URL, DEFAULT_PROFILE
+from .paths import VidbytePaths
+
+
+@dataclass(frozen=True)
+class MigrationResult:
+    """Safe migration facts that never contain copied content."""
+
+    config_copied: bool = False
+    credential_migrated: bool = False
+
+
+class StateMigration:
+    """Idempotently copy and verify supported legacy state."""
+
+    def __init__(
+        self,
+        paths: VidbytePaths,
+        config: ConfigStore,
+        keyring: KeyringCredentialStore,
+    ) -> None:
+        self._paths = paths
+        self._config = config
+        self._keyring = keyring
+
+    def migrate_if_needed(self) -> MigrationResult:
+        return MigrationResult(
+            config_copied=self._migrate_config(),
+            credential_migrated=self._migrate_credential(),
+        )
+
+    def _migrate_config(self) -> bool:
+        if self._paths.config_file().exists() or not self._paths.legacy_config_file().exists():
+            return False
+        snapshot = self._config.load()
+        if not snapshot.legacy:
+            return False
+        # No native file exists yet, so the expected digest is None by construction.
+        self._config.save(snapshot.document, expected_digest=None)
+        verified = self._config.load()
+        if verified.document != snapshot.document or verified.legacy:
+            raise MigrationVerificationFailed()
+        return True
+
+    def _migrate_credential(self) -> bool:
+        source = self._paths.legacy_credentials_file()
+        if not source.exists() or not self._keyring.available():
+            return False
+        if self._keyring.read(DEFAULT_PROFILE, DEFAULT_API_URL) is not None:
+            return False
+        try:
+            credentials = Credentials.model_validate(json.loads(source.read_bytes()))
+        except (OSError, json.JSONDecodeError, ValidationError) as error:
+            raise LegacyCredentialUnreadable(error) from error
+        self._keyring.write(credentials, DEFAULT_PROFILE, DEFAULT_API_URL)
+        read_back = self._keyring.read(DEFAULT_PROFILE, DEFAULT_API_URL)
+        if read_back is None or read_back.secret_value() != credentials.secret_value():
+            raise MigrationVerificationFailed()
+        return True

vidbyte_cli/lib/config/models.py

@@ -0,0 +1,145 @@
+"""The versioned, allow-listed shape of everything the CLI is willing to persist.
+
+`extra="forbid"` everywhere is deliberate: a typo in a hand-edited config file surfaces as a
+rejection rather than a setting that silently does nothing. `schema_version` is a `Literal`
+for the same reason — a future document is refused, never guessed at.
+
+Nothing here reads the environment or the filesystem, and no field may hold a secret;
+`ResolvedConfig` is the non-secret half of an invocation, `lib/auth` owns the other half.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from enum import StrEnum
+from typing import Annotated, Literal
+from urllib.parse import urlsplit, urlunsplit
+
+from pydantic import AfterValidator, BaseModel, ConfigDict, Field, field_validator
+
+from ..output import ColorMode, OutputFormat
+
+DEFAULT_API_URL = "https://vidbyte-backend.onrender.com"
+DEFAULT_PROFILE = "default"
+ProfileName = Annotated[str, Field(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_.-]+$")]
+
+
+class ConfigField(StrEnum):
+    """Public allow-list accepted by config get/set."""
+
+    API_URL = "api_url"
+    OUTPUT_FORMAT = "output_format"
+    COLOR = "color"
+    REQUEST_TIMEOUT_SECONDS = "request_timeout_seconds"
+
+
+class ConfigSource(StrEnum):
+    """Stable provenance values for effective non-secret settings."""
+
+    COMMAND = "command"
+    ENVIRONMENT = "environment"
+    SELECTED_PROFILE = "selected_profile"
+    DEFAULT_PROFILE = "default_profile"
+    BUILT_IN = "built_in"
+
+
+class ApiOrigin:
+    """The scheme/host/port an API base URL is allowed to be, parsed and re-rendered.
+
+    A base URL is an origin. Userinfo, a query, a fragment, or a path on one is either a
+    mistake or an attempt to redirect requests, so each is rejected rather than dropped — a
+    silently truncated URL sends credentials somewhere the caller never named.
+
+    Loopback detection lives here rather than beside it because the question is only ever
+    asked to decide whether cleartext HTTP is acceptable for this exact origin.
+    """
+
+    def __init__(self, scheme: str, host: str, port: int | None) -> None:
+        self.scheme = scheme
+        self.host = host
+        self.port = port
+
+    @classmethod
+    def parse(cls, value: str) -> ApiOrigin:
+        parsed = urlsplit(value.strip())
+        if parsed.scheme not in {"http", "https"} or parsed.hostname is None:
+            raise ValueError("API URL must be an absolute HTTP or HTTPS origin")
+        if parsed.username or parsed.password or parsed.query or parsed.fragment:
+            raise ValueError("API URL cannot contain credentials, a query, or a fragment")
+        if parsed.path not in {"", "/"}:
+            raise ValueError("API URL cannot contain a path")
+        origin = cls(parsed.scheme, parsed.hostname.lower(), parsed.port)
+        if origin.scheme == "http" and not origin.is_loopback:
+            raise ValueError("HTTP API URLs are restricted to loopback development hosts")
+        return origin
+
+    @classmethod
+    def normalize(cls, value: str) -> str:
+        # The pydantic entry point: validating and canonicalizing are one operation.
+        return str(cls.parse(value))
+
+    @property
+    def is_loopback(self) -> bool:
+        if self.host == "localhost":
+            return True
+        try:
+            return ipaddress.ip_address(self.host).is_loopback
+        except ValueError:
+            return False
+
+    def __str__(self) -> str:
+        # urlsplit strips the brackets an IPv6 literal needs to sit in a netloc; put them back.
+        host = f"[{self.host}]" if ":" in self.host else self.host
+        netloc = f"{host}:{self.port}" if self.port is not None else host
+        return urlunsplit((self.scheme, netloc, "", "", ""))
+
+
+NormalizedApiUrl = Annotated[str, AfterValidator(ApiOrigin.normalize)]
+
+
+class ProfileConfig(BaseModel):
+    """Non-secret settings owned by one named CLI profile."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    api_url: NormalizedApiUrl = DEFAULT_API_URL
+    output_format: OutputFormat = OutputFormat.HUMAN
+    color: ColorMode = ColorMode.AUTO
+    request_timeout_seconds: float = Field(default=30.0, ge=1.0, le=300.0)
+
+    @classmethod
+    def default_map(cls) -> dict[str, ProfileConfig]:
+        # A document always carries at least the default profile, so a fresh install
+        # resolves exactly like one that has been written to.
+        return {DEFAULT_PROFILE: cls()}
+
+
+class ConfigDocument(BaseModel):
+    """Version-one persisted config document."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = 1
+    active_profile: ProfileName = DEFAULT_PROFILE
+    profiles: dict[ProfileName, ProfileConfig] = Field(default_factory=ProfileConfig.default_map)
+
+    @field_validator("profiles")
+    @classmethod
+    def require_profiles(cls, value: dict[str, ProfileConfig]) -> dict[str, ProfileConfig]:
+        if not value:
+            raise ValueError("at least one profile is required")
+        return value
+
+
+class ResolvedConfig(BaseModel):
+    """Effective non-secret policy and its source for one invocation."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    profile: ProfileName
+    api_url: NormalizedApiUrl
+    output_format: OutputFormat
+    color: ColorMode
+    request_timeout_seconds: float = Field(ge=1.0, le=300.0)
+    provenance: dict[ConfigField, ConfigSource]
+    config_path: str | None = None

vidbyte_cli/lib/config/paths.py

@@ -0,0 +1,66 @@
+"""Single source of truth for every path the CLI reads or writes.
+
+Native locations come from platformdirs so config, cache, state, and data land where each
+platform expects them. The historical `~/.vidbyte` tree stays exposed, but only for
+compatible reads and verified migration — it is never the primary root again.
+
+Resolution is side-effect free on purpose: an instance can be constructed for `--help` or
+injected in a test without creating anything. Directories are created by the atomic writer
+performing an authorized mutation, never by asking where a file lives.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from platformdirs import PlatformDirs
+
+
+@dataclass(frozen=True)
+class VidbytePaths:
+    """Platform-native CLI state roots plus the read-compatible legacy root."""
+
+    config_root: Path
+    cache_root: Path
+    state_root: Path
+    data_root: Path
+    legacy_root: Path
+
+    @classmethod
+    def default(cls) -> VidbytePaths:
+        # platformdirs handles Windows, macOS, and freedesktop conventions consistently.
+        # roaming=False keeps credentials off a Windows roaming profile.
+        directories = PlatformDirs("vidbyte-cli", "Vidbyte", roaming=False)
+        return cls(
+            config_root=Path(directories.user_config_path),
+            cache_root=Path(directories.user_cache_path),
+            state_root=Path(directories.user_state_path),
+            data_root=Path(directories.user_data_path),
+            legacy_root=Path.home() / ".vidbyte",
+        )
+
+    def config_file(self) -> Path:
+        return self.config_root / "config.json"
+
+    def credentials_file(self) -> Path:
+        # Data, not config: the fallback credential file must not be synced or shared as a
+        # settings file, and must never sit in the cache the CLI may clear.
+        return self.data_root / "credentials.json"
+
+    def operations_dir(self) -> Path:
+        return self.state_root / "operations"
+
+    def legacy_config_file(self) -> Path:
+        return self.legacy_root / "config.json"
+
+    def legacy_credentials_file(self) -> Path:
+        return self.legacy_root / "credentials.json"
+
+    def provider_credentials_file(self) -> Path:
+        # Data, not config: provider fallback keys must not be synced as settings.
+        return self.data_root / "provider-credentials.json"
+
+    def suggestions_dir(self) -> Path:
+        # Durable suggestion memory belongs beside other local user data, not cache state.
+        return self.data_root / "suggestions"

vidbyte_cli/lib/config/resolver.py

@@ -0,0 +1,137 @@
+"""Where one invocation's effective non-secret settings come from, and which layer won.
+
+Precedence is command → environment → selected profile → default profile → built-in, and
+every field records which of those supplied it. Provenance is not decoration: `config get`
+reports the effective value, and without a source a user cannot tell a stored setting from
+an environment variable they forgot was exported.
+
+Resolution is read-only and deterministic for an injected environment — it never migrates,
+never writes, and never touches a secret. `CredentialResolver` owns that separate order.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import TypeVar
+
+from pydantic import ValidationError
+
+from ..errors.failures import InvalidConfigOverride
+from ..output import ColorMode, OutputFormat
+from .config import ConfigStore
+from .models import (
+    DEFAULT_API_URL,
+    DEFAULT_PROFILE,
+    ConfigField,
+    ConfigSource,
+    ProfileConfig,
+    ResolvedConfig,
+)
+
+_T = TypeVar("_T")
+
+
+@dataclass(frozen=True)
+class ConfigOverrides:
+    """Explicit root values that outrank environment and stored profiles."""
+
+    profile: str | None = None
+    api_url: str | None = None
+    output_format: OutputFormat | None = None
+    color: ColorMode | None = None
+    request_timeout_seconds: float | None = None
+
+
+class ConfigResolver:
+    """Resolve typed invocation settings and retain how each value was chosen."""
+
+    def __init__(self, store: ConfigStore, environment: Mapping[str, str]) -> None:
+        self._store = store
+        self._environment = environment
+
+    def resolve(self, overrides: ConfigOverrides | None = None) -> ResolvedConfig:
+        explicit = overrides or ConfigOverrides()
+        snapshot = self._store.load()
+        document = snapshot.document
+        profile = explicit.profile or self._environment.get("VIDBYTE_PROFILE")
+        profile = profile or document.active_profile or DEFAULT_PROFILE
+        # With no file on disk the document is built-in defaults, so its profiles must not be
+        # reported as a stored source the user could go and edit.
+        stored = document.profiles if snapshot.path is not None else {}
+        selected = stored.get(profile)
+        default = stored.get(DEFAULT_PROFILE)
+        base = selected or default or ProfileConfig()
+        base_source = self._profile_source(selected, default)
+        try:
+            api_url, api_source = self._resolve_value(
+                explicit.api_url,
+                self._environment.get("VIDBYTE_API_URL"),
+                base.api_url,
+                base_source,
+                str,
+            )
+            output, output_source = self._resolve_value(
+                explicit.output_format,
+                self._environment.get("VIDBYTE_OUTPUT_FORMAT"),
+                base.output_format,
+                base_source,
+                OutputFormat,
+            )
+            color, color_source = self._resolve_value(
+                explicit.color,
+                self._environment.get("VIDBYTE_COLOR"),
+                base.color,
+                base_source,
+                ColorMode,
+            )
+            timeout, timeout_source = self._resolve_value(
+                explicit.request_timeout_seconds,
+                self._environment.get("VIDBYTE_REQUEST_TIMEOUT_SECONDS"),
+                base.request_timeout_seconds,
+                base_source,
+                float,
+            )
+            return ResolvedConfig(
+                profile=profile,
+                api_url=api_url or DEFAULT_API_URL,
+                output_format=output,
+                color=color,
+                request_timeout_seconds=timeout,
+                provenance={
+                    ConfigField.API_URL: api_source,
+                    ConfigField.OUTPUT_FORMAT: output_source,
+                    ConfigField.COLOR: color_source,
+                    ConfigField.REQUEST_TIMEOUT_SECONDS: timeout_source,
+                },
+                config_path=str(snapshot.path) if snapshot.path is not None else None,
+            )
+        except (ValidationError, ValueError) as error:
+            raise InvalidConfigOverride(error) from error
+
+    def _resolve_value(
+        self,
+        command: _T | None,
+        environment: str | None,
+        profile: _T,
+        profile_source: ConfigSource,
+        parser: Callable[[str], _T],
+    ) -> tuple[_T, ConfigSource]:
+        # An exported-but-empty variable is treated as unset; the alternative is a shell
+        # that silently forces built-in defaults on every invocation.
+        if command is not None:
+            return command, ConfigSource.COMMAND
+        if environment is not None and environment.strip():
+            return parser(environment.strip()), ConfigSource.ENVIRONMENT
+        return profile, profile_source
+
+    def _profile_source(
+        self,
+        selected: ProfileConfig | None,
+        default: ProfileConfig | None,
+    ) -> ConfigSource:
+        if selected is not None:
+            return ConfigSource.SELECTED_PROFILE
+        if default is not None:
+            return ConfigSource.DEFAULT_PROFILE
+        return ConfigSource.BUILT_IN

vidbyte_cli/lib/constants/__init__.py

@@ -0,0 +1 @@
+"""Canonical enum constants shared by CLI runtime policy and execution."""