originalpictures-cli 0.1.0__py3-none-any.whl

originalpictures_cli/__init__.py

@@ -0,0 +1,7 @@
+"""Original Pictures command-line client."""
+
+from originalpictures_cli.exit_codes import ExitCode
+
+__version__ = "0.1.0"
+
+__all__ = ["ExitCode", "__version__"]

originalpictures_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Module entry point for ``python -m originalpictures_cli``."""
+
+from originalpictures_cli.cli import main
+
+main()

originalpictures_cli/cli.py

@@ -0,0 +1,162 @@
+"""Click command tree for Original Pictures public workflows."""
+
+from __future__ import annotations
+
+import click
+
+from originalpictures_cli import __version__
+from originalpictures_cli.click_boundary import JsonUsageGroup
+from originalpictures_cli.config import ConfigStore
+from originalpictures_cli.operations import register_operation_commands
+from originalpictures_cli.output import Output
+from originalpictures_cli.runtime import Runtime, invoke
+from originalpictures_cli.workflows import register_workflow_commands
+
+
+@click.group(
+    cls=JsonUsageGroup,
+    context_settings={"help_option_names": ["-h", "--help"], "max_content_width": 100},
+    help="Reviewed Original Pictures public API workflows.",
+    epilog="Root options must appear before the command group (for example: --json jobs get).",
+)
+@click.version_option(__version__, prog_name="Original Pictures CLI")
+@click.option("--json", "json_mode", is_flag=True, help="Emit deterministic JSON on stdout.")
+@click.option("--profile", help="Named local profile (or ORIGINALPICTURES_PROFILE).")
+@click.option("--api-url", help="One-run API URL override (or ORIGINALPICTURES_API_URL).")
+@click.option(
+    "--timeout",
+    type=click.FloatRange(0.1, 600.0),
+    default=30.0,
+    show_default=True,
+    help="Per-request SDK timeout in seconds.",
+)
+@click.option(
+    "--max-response-bytes",
+    type=click.IntRange(1024, 64 * 1024 * 1024),
+    default=16 * 1024 * 1024,
+    show_default=True,
+    help="Hard SDK JSON response bound.",
+)
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    json_mode: bool,
+    profile: str | None,
+    api_url: str | None,
+    timeout: float,
+    max_response_bytes: int,
+) -> None:
+    """Initialize a lazy SDK runtime; no network call occurs for help/config commands."""
+
+    output = Output(json_mode=json_mode)
+    if isinstance(ctx.obj, Runtime):
+        runtime = ctx.obj
+        runtime.output = output
+        runtime.profile_name = profile or runtime.profile_name
+        runtime.api_url = api_url or runtime.api_url
+        runtime.timeout = timeout
+        runtime.max_response_bytes = max_response_bytes
+    else:
+        runtime = Runtime(
+            store=ConfigStore(),
+            output=output,
+            profile_name=profile,
+            api_url=api_url,
+            timeout=timeout,
+            max_response_bytes=max_response_bytes,
+        )
+    ctx.obj = runtime
+    ctx.call_on_close(runtime.close)
+
+
+@cli.group("auth", help="Store and inspect API credentials without argv secrets.")
+def auth_group() -> None:
+    pass
+
+
+@auth_group.command("login", help="Store an API credential in the operating-system keyring.")
+@click.option(
+    "--token-stdin",
+    is_flag=True,
+    help="Read one credential line from stdin instead of hidden interactive input.",
+)
+@click.pass_obj
+def auth_login(runtime: Runtime, token_stdin: bool) -> None:
+    if token_stdin:
+        token = click.get_text_stream("stdin").readline(4098)
+        if len(token) > 4097 or (token and not token.endswith("\n")):
+            raise click.UsageError("credential input exceeds the 4096-character limit")
+        token = token.rstrip("\r\n")
+    else:
+        token = click.prompt("API credential", hide_input=True, confirmation_prompt=True)
+    profile_name = runtime.profile_name or runtime.store.default_profile
+    invoke(runtime, lambda: runtime.store.set_api_key(profile_name, token))
+    runtime.output.success({"credential_stored": True, "profile": profile_name})
+
+
+@auth_group.command("logout", help="Remove a profile credential from the keyring.")
+@click.pass_obj
+def auth_logout(runtime: Runtime) -> None:
+    profile_name = runtime.profile_name or runtime.store.default_profile
+    removed = invoke(runtime, lambda: runtime.store.delete_api_key(profile_name))
+    runtime.output.success({"credential_removed": bool(removed), "profile": profile_name})
+
+
+@auth_group.command("status", help="Show credential presence and source, never its value.")
+@click.pass_obj
+def auth_status(runtime: Runtime) -> None:
+    profile = invoke(runtime, lambda: runtime.profile)
+    runtime.output.success(
+        {
+            "api_url": profile.api_url,
+            "credential_configured": profile.api_key is not None,
+            "credential_source": profile.credential_source,
+            "profile": profile.name,
+        }
+    )
+
+
+@cli.group("config", help="Manage non-secret local profile configuration.")
+def config_group() -> None:
+    pass
+
+
+@config_group.command("set-api-url", help="Set a profile API URL (credentials are rejected).")
+@click.argument("url")
+@click.pass_obj
+def config_set_api_url(runtime: Runtime, url: str) -> None:
+    profile_name = runtime.profile_name or runtime.store.default_profile
+    profile = invoke(runtime, lambda: runtime.store.set_api_url(profile_name, url))
+    runtime.output.success({"api_url": profile.api_url, "profile": profile.name})
+
+
+@config_group.command("show", help="Show the selected non-secret profile configuration.")
+@click.pass_obj
+def config_show(runtime: Runtime) -> None:
+    profile = invoke(runtime, lambda: runtime.profile)
+    runtime.output.success(
+        {
+            "api_url": profile.api_url,
+            "credential_configured": profile.api_key is not None,
+            "profile": profile.name,
+        }
+    )
+
+
+@config_group.command("profiles", help="List configured profiles without credential values.")
+@click.pass_obj
+def config_profiles(runtime: Runtime) -> None:
+    profiles = invoke(runtime, runtime.store.list_profiles)
+    runtime.output.success({"profiles": profiles})
+
+
+def main() -> None:
+    """Console script entry point."""
+
+    cli()
+
+
+register_operation_commands(cli)
+register_workflow_commands(cli)
+
+__all__ = ["cli", "main"]

originalpictures_cli/click_boundary.py

@@ -0,0 +1,69 @@
+"""Root Click error boundary for deterministic machine-readable usage failures."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+from typing import Any
+
+import click
+
+from originalpictures_cli.exit_codes import ExitCode
+from originalpictures_cli.output import canonical_json
+
+
+class JsonUsageGroup(click.Group):
+    """Preserve normal Click UX while making ``--json`` parsing errors canonical."""
+
+    def main(
+        self,
+        args: Sequence[str] | None = None,
+        prog_name: str | None = None,
+        complete_var: str | None = None,
+        standalone_mode: bool = True,
+        windows_expand_args: bool = True,
+        **extra: Any,
+    ) -> Any:
+        resolved_args = list(args) if args is not None else sys.argv[1:]
+        json_requested = any(
+            argument == "--json" or argument.startswith("--json=") for argument in resolved_args
+        )
+        try:
+            result = super().main(
+                args=resolved_args,
+                prog_name=prog_name,
+                complete_var=complete_var,
+                standalone_mode=False,
+                windows_expand_args=windows_expand_args,
+                **extra,
+            )
+            if standalone_mode and isinstance(result, int):
+                raise SystemExit(result)
+            return result
+        except click.ClickException as error:
+            if json_requested:
+                payload = {
+                    "error": {
+                        "exit_code": int(ExitCode.USAGE),
+                        "kind": "usage",
+                        "message": error.format_message(),
+                    }
+                }
+                click.echo(canonical_json(payload), err=True)
+            elif standalone_mode:
+                error.show()
+            if standalone_mode:
+                raise SystemExit(int(ExitCode.USAGE)) from None
+            raise
+        except click.exceptions.Exit as error:
+            if standalone_mode:
+                raise SystemExit(error.exit_code) from None
+            raise
+        except click.Abort:
+            if standalone_mode:
+                click.echo("Aborted!", err=True)
+                raise SystemExit(int(ExitCode.UNEXPECTED)) from None
+            raise
+
+
+__all__ = ["JsonUsageGroup"]

originalpictures_cli/config.py

@@ -0,0 +1,222 @@
+"""Non-secret profile configuration and OS keyring credential storage."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import stat
+import tempfile
+from collections.abc import Mapping, MutableMapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+from urllib.parse import urlsplit
+
+import keyring
+from platformdirs import PlatformDirs
+
+DEFAULT_API_URL = "http://localhost:8000"
+DEFAULT_PROFILE = "default"
+MAX_CONFIG_BYTES = 256 * 1024
+_PROFILE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$")
+
+
+class ConfigurationFailure(ValueError):
+    """Local configuration is absent, unsafe, or invalid."""
+
+
+class CredentialBackend(Protocol):
+    def get_password(self, service_name: str, username: str) -> str | None: ...
+
+    def set_password(self, service_name: str, username: str, password: str) -> None: ...
+
+    def delete_password(self, service_name: str, username: str) -> None: ...
+
+
+@dataclass(frozen=True)
+class ResolvedProfile:
+    name: str
+    api_url: str
+    api_key: str | None
+    credential_source: str | None
+
+
+class ConfigStore:
+    """Read profile settings from platformdirs and credentials from keyring."""
+
+    service_name = "originalpictures-cli"
+
+    def __init__(
+        self,
+        *,
+        config_dir: Path | None = None,
+        credential_backend: CredentialBackend | None = None,
+        environ: Mapping[str, str] | None = None,
+    ) -> None:
+        platform_dir = PlatformDirs("Original Pictures", "Original Pictures").user_config_path
+        self.config_dir = config_dir or platform_dir
+        self.path = self.config_dir / "config.json"
+        self._credentials = credential_backend or keyring
+        self._environ = environ if environ is not None else os.environ
+
+    @property
+    def default_profile(self) -> str:
+        return validate_profile_name(self._environ.get("ORIGINALPICTURES_PROFILE", DEFAULT_PROFILE))
+
+    def resolve(self, *, profile: str | None = None, api_url: str | None = None) -> ResolvedProfile:
+        name = validate_profile_name(profile or self.default_profile)
+        data = self._load()
+        profiles = data.get("profiles", {})
+        if not isinstance(profiles, dict):
+            raise ConfigurationFailure("configuration profiles must be an object")
+        profile_data = profiles.get(name, {})
+        if not isinstance(profile_data, dict):
+            raise ConfigurationFailure(f"profile {name!r} is malformed")
+        configured_url = profile_data.get("api_url", DEFAULT_API_URL)
+        env_url = self._environ.get("ORIGINALPICTURES_API_URL")
+        resolved_url = validate_api_url(api_url or env_url or configured_url)
+
+        env_key = self._environ.get("ORIGINALPICTURES_API_KEY")
+        if env_key:
+            return ResolvedProfile(name, resolved_url, _validate_api_key(env_key), "environment")
+        try:
+            stored_key = self._credentials.get_password(self.service_name, name)
+        except Exception as error:  # keyring backends expose platform-specific exceptions
+            raise ConfigurationFailure("the operating-system keyring is unavailable") from error
+        if stored_key:
+            return ResolvedProfile(name, resolved_url, _validate_api_key(stored_key), "keyring")
+        return ResolvedProfile(name, resolved_url, None, None)
+
+    def set_api_url(self, profile: str, api_url: str) -> ResolvedProfile:
+        name = validate_profile_name(profile)
+        validated_url = validate_api_url(api_url)
+        data = self._load()
+        profiles = data.setdefault("profiles", {})
+        if not isinstance(profiles, dict):
+            raise ConfigurationFailure("configuration profiles must be an object")
+        profiles[name] = {"api_url": validated_url}
+        self._save(data)
+        return ResolvedProfile(name, validated_url, None, None)
+
+    def set_api_key(self, profile: str, api_key: str) -> None:
+        name = validate_profile_name(profile)
+        validated_key = _validate_api_key(api_key)
+        try:
+            self._credentials.set_password(self.service_name, name, validated_key)
+        except Exception as error:
+            raise ConfigurationFailure(
+                "the operating-system keyring rejected the credential"
+            ) from error
+
+    def delete_api_key(self, profile: str) -> bool:
+        name = validate_profile_name(profile)
+        try:
+            if self._credentials.get_password(self.service_name, name) is None:
+                return False
+            self._credentials.delete_password(self.service_name, name)
+        except Exception as error:
+            raise ConfigurationFailure(
+                "the operating-system keyring could not remove the credential"
+            ) from error
+        return True
+
+    def list_profiles(self) -> list[dict[str, object]]:
+        data = self._load()
+        profiles = data.get("profiles", {})
+        if not isinstance(profiles, dict):
+            raise ConfigurationFailure("configuration profiles must be an object")
+        names = sorted(set(profiles) | {self.default_profile})
+        result: list[dict[str, object]] = []
+        for name in names:
+            resolved = self.resolve(profile=name)
+            result.append(
+                {
+                    "api_url": resolved.api_url,
+                    "credential_configured": resolved.api_key is not None,
+                    "credential_source": resolved.credential_source,
+                    "name": name,
+                }
+            )
+        return result
+
+    def _load(self) -> MutableMapping[str, object]:
+        if not self.path.exists():
+            return {"profiles": {}}
+        if self.path.is_symlink():
+            raise ConfigurationFailure("refusing to read a symlinked configuration file")
+        file_mode = stat.S_IMODE(self.path.stat().st_mode)
+        if file_mode & 0o077:
+            raise ConfigurationFailure(
+                "configuration permissions must not allow group/other access"
+            )
+        if self.path.stat().st_size > MAX_CONFIG_BYTES:
+            raise ConfigurationFailure("configuration file exceeds the 256 KiB limit")
+        try:
+            value = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError, json.JSONDecodeError) as error:
+            raise ConfigurationFailure("configuration file is not valid UTF-8 JSON") from error
+        if not isinstance(value, dict):
+            raise ConfigurationFailure("configuration root must be an object")
+        return value
+
+    def _save(self, data: Mapping[str, object]) -> None:
+        self.config_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+        try:
+            os.chmod(self.config_dir, 0o700)
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                encoding="utf-8",
+                dir=self.config_dir,
+                prefix=".config-",
+                suffix=".json",
+                delete=False,
+            ) as temporary:
+                json.dump(
+                    data, temporary, ensure_ascii=False, separators=(",", ":"), sort_keys=True
+                )
+                temporary.write("\n")
+                temporary.flush()
+                os.fsync(temporary.fileno())
+                temporary_path = Path(temporary.name)
+            os.chmod(temporary_path, 0o600)
+            os.replace(temporary_path, self.path)
+        except OSError as error:
+            raise ConfigurationFailure("configuration could not be written securely") from error
+
+
+def validate_profile_name(value: str) -> str:
+    if not _PROFILE_RE.fullmatch(value):
+        raise ConfigurationFailure(
+            "profile name must be 1-64 letters, digits, dots, underscores, or hyphens"
+        )
+    return value
+
+
+def validate_api_url(value: object) -> str:
+    if not isinstance(value, str):
+        raise ConfigurationFailure("API URL must be a string")
+    parsed = urlsplit(value)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        raise ConfigurationFailure("API URL must be an absolute http(s) URL")
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise ConfigurationFailure("API URL must not contain credentials, a query, or a fragment")
+    return value.rstrip("/")
+
+
+def _validate_api_key(value: str) -> str:
+    stripped = value.strip()
+    if not stripped or len(stripped) > 4096 or any(char.isspace() for char in stripped):
+        raise ConfigurationFailure("API credential must be 1-4096 non-whitespace characters")
+    return stripped
+
+
+__all__ = [
+    "ConfigurationFailure",
+    "ConfigStore",
+    "DEFAULT_API_URL",
+    "DEFAULT_PROFILE",
+    "ResolvedProfile",
+    "validate_api_url",
+    "validate_profile_name",
+]

originalpictures_cli/exit_codes.py

@@ -0,0 +1,24 @@
+"""Documented process exit codes for scripts and operators."""
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    SUCCESS = 0
+    UNEXPECTED = 1
+    USAGE = 2
+    CONFIGURATION = 3
+    VALIDATION = 4
+    AUTHENTICATION = 5
+    PERMISSION = 6
+    NOT_FOUND = 7
+    CONFLICT = 8
+    RATE_LIMIT = 9
+    DEADLINE = 10
+    UNAVAILABLE = 11
+    INTEGRITY = 12
+    TOO_LARGE = 13
+    CANCELLED = 130
+
+
+__all__ = ["ExitCode"]