holocubic-cli-python 0.1.0__py3-none-any.whl

holocubic_cli_python/client.py

@@ -0,0 +1,375 @@
+"""Validated HoloCubic DevTools API v1 client."""
+
+from typing import Any
+
+from .errors import CubicError, is_not_found
+from .models import (
+    LEGACY_V1_CAPABILITIES,
+    AppsResult,
+    DeviceInfo,
+    DevRunResult,
+    ListResult,
+    ReadChunk,
+    RemoteEntry,
+    RemoteStat,
+    UploadResult,
+)
+from .remote_path import normalize_remote_path
+from .transport import HttpTransport
+
+
+DEFAULT_MAX_CODE_BYTES = 192 * 1024
+
+
+def _object(value: Any, label: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise CubicError(
+            f"Device returned an invalid {label} response.", code="INVALID_RESPONSE"
+        )
+    return value
+
+
+def _string(value: Any, label: str) -> str:
+    if not isinstance(value, str):
+        raise CubicError(
+            f"Device response is missing {label}.", code="INVALID_RESPONSE"
+        )
+    return value
+
+
+def _integer(value: Any, label: str, minimum: int = 0) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value < minimum:
+        raise CubicError(
+            f"Device response has an invalid {label}.", code="INVALID_RESPONSE"
+        )
+    return value
+
+
+def _bool(value: Any, label: str) -> bool:
+    if not isinstance(value, bool):
+        raise CubicError(
+            f"Device response has an invalid {label}.", code="INVALID_RESPONSE"
+        )
+    return value
+
+
+def _lua_array(value: Any, label: str) -> list[Any]:
+    if isinstance(value, list):
+        return value
+    if isinstance(value, dict) and not value:
+        return []
+    raise CubicError(
+        f"Device {label} response is missing a valid array.", code="INVALID_RESPONSE"
+    )
+
+
+def _entry(value: Any) -> RemoteEntry:
+    item = _object(value, "directory entry")
+    return RemoteEntry(
+        name=_string(item.get("name"), "entry.name"),
+        path=normalize_remote_path(_string(item.get("path"), "entry.path")),
+        size=_integer(item.get("size"), "entry.size"),
+        is_dir=_bool(item.get("is_dir"), "entry.is_dir"),
+        ext=item.get("ext") if isinstance(item.get("ext"), str) else "",
+        mime=item.get("mime")
+        if isinstance(item.get("mime"), str)
+        else "application/octet-stream",
+        category=item.get("category")
+        if isinstance(item.get("category"), str)
+        else "other",
+    )
+
+
+class CubicClient:
+    def __init__(self, base_url: str, timeout_ms: int = 60_000) -> None:
+        self.transport = HttpTransport(base_url, timeout_ms)
+        self._cached_info: DeviceInfo | None = None
+
+    def info(self, force: bool = False) -> DeviceInfo:
+        if self._cached_info is not None and not force:
+            return self._cached_info
+        raw = _object(self.transport.json("info"), "info")
+        if raw.get("ok") is not True:
+            raise CubicError(
+                "Device handshake did not return ok=true.", code="INVALID_RESPONSE"
+            )
+        api_version = (
+            1
+            if raw.get("api_version") is None
+            else _integer(raw.get("api_version"), "api_version", 1)
+        )
+        if api_version > 1:
+            raise CubicError(
+                f"Unsupported DevTools API version: {api_version}.",
+                code="UNSUPPORTED_API",
+            )
+        root_path = _string(raw.get("root_path"), "root_path")
+        if normalize_remote_path(root_path) != "/sd":
+            raise CubicError(
+                f"Unsupported device root path: {root_path}.", code="INVALID_RESPONSE"
+            )
+        explicit = raw.get("capabilities")
+        capabilities = (
+            tuple(item for item in explicit if isinstance(item, str))
+            if isinstance(explicit, list)
+            else LEGACY_V1_CAPABILITIES
+        )
+        info = DeviceInfo(
+            api_version=api_version,
+            version=raw.get("version") if isinstance(raw.get("version"), str) else None,
+            route_base=raw.get("route_base")
+            if isinstance(raw.get("route_base"), str)
+            else "/devtools",
+            root_path=root_path,
+            chunk_size=_integer(raw.get("chunk_size"), "chunk_size", 1),
+            max_file_size=_integer(raw.get("max_file_size"), "max_file_size", 1),
+            max_code_bytes=(
+                DEFAULT_MAX_CODE_BYTES
+                if raw.get("max_code_bytes") is None
+                else _integer(raw.get("max_code_bytes"), "max_code_bytes", 1)
+            ),
+            run_app_id=_string(raw.get("run_app_id"), "run_app_id"),
+            run_app_main=normalize_remote_path(
+                _string(raw.get("run_app_main"), "run_app_main")
+            ),
+            capabilities=capabilities,
+            raw=raw,
+        )
+        self._cached_info = info
+        return info
+
+    def require_capability(self, capability: str) -> None:
+        if capability not in self.info().capabilities:
+            raise CubicError(
+                f"Device does not support capability {capability}.",
+                code="UNSUPPORTED_CAPABILITY",
+            )
+
+    def list(self, remote_path: str = "/sd") -> ListResult:
+        self.require_capability("fs.list")
+        raw = _object(
+            self.transport.json(
+                "list", query={"path": normalize_remote_path(remote_path)}
+            ),
+            "list",
+        )
+        return ListResult(
+            path=normalize_remote_path(_string(raw.get("path"), "list.path")),
+            parent=normalize_remote_path(_string(raw.get("parent"), "list.parent")),
+            dir_count=_integer(raw.get("dir_count"), "list.dir_count"),
+            file_count=_integer(raw.get("file_count"), "list.file_count"),
+            total_bytes=_integer(raw.get("total_bytes"), "list.total_bytes"),
+            items=tuple(
+                _entry(item) for item in _lua_array(raw.get("items"), "list.items")
+            ),
+        )
+
+    def stat(self, remote_path: str) -> RemoteStat:
+        self.require_capability("fs.stat")
+        raw = _object(
+            self.transport.json(
+                "stat", query={"path": normalize_remote_path(remote_path)}
+            ),
+            "stat",
+        )
+        return RemoteStat(
+            path=normalize_remote_path(_string(raw.get("path"), "stat.path")),
+            name=_string(raw.get("name"), "stat.name"),
+            parent=normalize_remote_path(_string(raw.get("parent"), "stat.parent")),
+            size=_integer(raw.get("size"), "stat.size"),
+            is_dir=_bool(raw.get("is_dir"), "stat.is_dir"),
+            ext=raw.get("ext") if isinstance(raw.get("ext"), str) else "",
+            mime=raw.get("mime")
+            if isinstance(raw.get("mime"), str)
+            else "application/octet-stream",
+            category=raw.get("category")
+            if isinstance(raw.get("category"), str)
+            else "other",
+        )
+
+    def stat_or_none(self, remote_path: str) -> RemoteStat | None:
+        try:
+            return self.stat(remote_path)
+        except CubicError as error:
+            if is_not_found(error):
+                return None
+            raise
+
+    def read(self, remote_path: str, offset: int, size: int) -> ReadChunk:
+        self.require_capability("fs.read")
+        response = self.transport.request(
+            "read",
+            query={
+                "path": normalize_remote_path(remote_path),
+                "offset": offset,
+                "size": size,
+            },
+            headers={"Accept": "application/octet-stream"},
+        )
+        lower_headers = {key.lower(): value for key, value in response.headers.items()}
+        try:
+            file_size = int(lower_headers["x-file-size"])
+            next_offset = int(lower_headers["x-next-offset"])
+        except (KeyError, ValueError) as error:
+            raise CubicError(
+                "Device response has invalid read headers.", code="INVALID_RESPONSE"
+            ) from error
+        if file_size < 0 or next_offset < 0:
+            raise CubicError(
+                "Device response has invalid read headers.", code="INVALID_RESPONSE"
+            )
+        return ReadChunk(
+            data=response.body,
+            size=file_size,
+            next_offset=next_offset,
+            eof=lower_headers.get("x-eof") == "1",
+            name=lower_headers.get("x-file-name", ""),
+            mime=lower_headers.get("content-type", "application/octet-stream"),
+        )
+
+    def mkdir(self, remote_path: str) -> None:
+        self.require_capability("fs.mkdir")
+        self.transport.json(
+            "mkdir", method="POST", query={"path": normalize_remote_path(remote_path)}
+        )
+
+    def rename(self, source: str, target: str) -> None:
+        self.require_capability("fs.rename")
+        self.transport.json(
+            "rename",
+            method="POST",
+            query={
+                "path": normalize_remote_path(source),
+                "new_path": normalize_remote_path(target),
+            },
+        )
+
+    def upload(
+        self, remote_path: str, data: bytes, offset: int, total: int
+    ) -> UploadResult:
+        self.require_capability("fs.write")
+        raw = _object(
+            self.transport.json(
+                "upload",
+                method="PUT",
+                query={
+                    "path": normalize_remote_path(remote_path),
+                    "offset": offset,
+                    "total": total,
+                },
+                body=data,
+                headers={"Content-Type": "application/octet-stream"},
+            ),
+            "upload",
+        )
+        next_offset = _integer(raw.get("next_offset"), "upload.next_offset")
+        return UploadResult(
+            path=normalize_remote_path(_string(raw.get("path"), "upload.path")),
+            next_offset=next_offset,
+            total=_integer(raw.get("total"), "upload.total"),
+            done=_bool(raw.get("done"), "upload.done"),
+            size=next_offset
+            if raw.get("size") is None
+            else _integer(raw.get("size"), "upload.size"),
+        )
+
+    def remove(self, remote_path: str) -> None:
+        self.require_capability("fs.remove")
+        self.transport.json(
+            "remove",
+            method="DELETE",
+            query={"path": normalize_remote_path(remote_path)},
+        )
+
+    def rmdir(self, remote_path: str, recursive: bool = False) -> None:
+        self.require_capability("fs.rmdir")
+        self.transport.json(
+            "rmdir",
+            method="DELETE",
+            query={
+                "path": normalize_remote_path(remote_path),
+                "recursive": 1 if recursive else 0,
+            },
+        )
+
+    def apps(self) -> AppsResult:
+        self.require_capability("apps.list")
+        raw = _object(self.transport.json("apps"), "apps")
+        apps = tuple(
+            item
+            for item in _lua_array(raw.get("apps"), "apps.apps")
+            if isinstance(item, dict)
+        )
+        current = (
+            raw.get("current_app_id")
+            if isinstance(raw.get("current_app_id"), str)
+            else None
+        )
+        return AppsResult(
+            apps=apps,
+            current_app_id=current,
+            run_app_id=_string(raw.get("run_app_id"), "apps.run_app_id"),
+            run_app_main=normalize_remote_path(
+                _string(raw.get("run_app_main"), "apps.run_app_main")
+            ),
+        )
+
+    def read_devrun(self) -> str:
+        self.require_capability("devrun.read")
+        response = self.transport.request("code/read", headers={"Accept": "text/plain"})
+        try:
+            return response.body.decode("utf-8")
+        except UnicodeDecodeError as error:
+            raise CubicError(
+                "Device returned invalid UTF-8 DevRun source.", code="INVALID_RESPONSE"
+            ) from error
+
+    def save_devrun(self, source: str, run: bool = False) -> DevRunResult:
+        self.require_capability("devrun.run" if run else "devrun.save")
+        encoded = source.encode("utf-8")
+        info = self.info()
+        if len(encoded) > info.max_code_bytes:
+            raise CubicError(
+                f"DevRun source is {len(encoded)} bytes; device limit is {info.max_code_bytes} bytes.",
+                code="FILE_TOO_LARGE",
+            )
+        raw = _object(
+            self.transport.json(
+                "code/run" if run else "code/save",
+                method="POST",
+                body=encoded,
+                headers={"Content-Type": "text/plain; charset=utf-8"},
+            ),
+            "DevRun",
+        )
+        return DevRunResult(
+            id=_string(raw.get("id"), "DevRun.id"),
+            entry=normalize_remote_path(_string(raw.get("entry"), "DevRun.entry")),
+            bytes=_integer(raw.get("bytes"), "DevRun.bytes"),
+            launched=_bool(raw.get("launched"), "DevRun.launched"),
+            rescan_requested=_bool(
+                raw.get("rescan_requested"), "DevRun.rescan_requested"
+            ),
+        )
+
+
+def public_info(info: DeviceInfo, url: str, name: str | None = None) -> dict[str, Any]:
+    return {
+        "name": name,
+        "url": url,
+        "version": info.version,
+        "api_version": info.api_version,
+        "route_base": info.route_base,
+        "root_path": info.root_path,
+        "chunk_size": info.chunk_size,
+        "max_file_size": info.max_file_size,
+        "max_code_bytes": info.max_code_bytes,
+        "run_app_id": info.run_app_id,
+        "run_app_main": info.run_app_main,
+        "capabilities": list(info.capabilities),
+    }
+
+
+def fetch_info(host: str, timeout_ms: int = 60_000) -> dict[str, Any]:
+    client = CubicClient(host, timeout_ms)
+    return public_info(client.info(force=True), client.transport.base_url)

holocubic_cli_python/config.py

@@ -0,0 +1,133 @@
+"""Named device configuration with atomic JSON persistence."""
+
+import json
+import os
+import secrets
+from pathlib import Path
+from typing import Any, Mapping
+
+from .errors import CubicError, UsageError
+from .url import normalize_device_url
+
+
+def default_config_path(
+    env: Mapping[str, str] | None = None, platform: str | None = None
+) -> Path:
+    values = os.environ if env is None else env
+    if values.get("CUBIC_CONFIG"):
+        return Path(values["CUBIC_CONFIG"]).expanduser().resolve()
+    target_platform = platform or os.name
+    if target_platform in {"nt", "win32"}:
+        base = Path(values.get("APPDATA", Path.home() / "AppData" / "Roaming"))
+    else:
+        base = Path(values.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+    return base / "cubic" / "config.json"
+
+
+def validate_device_name(name: str) -> str:
+    trimmed = name.strip()
+    if (
+        not trimmed
+        or trimmed in {".", ".."}
+        or "/" in trimmed
+        or "\\" in trimmed
+        or any(ord(character) < 32 for character in trimmed)
+    ):
+        raise UsageError(f"Invalid device name: {name}")
+    return trimmed
+
+
+class ConfigStore:
+    def __init__(self, file_path: str | Path | None = None) -> None:
+        self.file_path = (
+            Path(file_path).resolve()
+            if file_path is not None
+            else default_config_path()
+        )
+
+    def read(self) -> dict[str, Any]:
+        try:
+            parsed = json.loads(self.file_path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return {"version": 1, "current": None, "devices": {}}
+        except (OSError, json.JSONDecodeError) as error:
+            raise CubicError(
+                f"Unable to read config {self.file_path}.", code="CONFIG_ERROR"
+            ) from error
+        if (
+            not isinstance(parsed, dict)
+            or parsed.get("version") != 1
+            or not isinstance(parsed.get("devices"), dict)
+        ):
+            raise CubicError(
+                f"Config {self.file_path} has an unsupported format.",
+                code="CONFIG_ERROR",
+            )
+        devices: dict[str, dict[str, str]] = {}
+        for name, raw_profile in parsed["devices"].items():
+            if (
+                not isinstance(name, str)
+                or not isinstance(raw_profile, dict)
+                or not isinstance(raw_profile.get("url"), str)
+            ):
+                continue
+            profile = {"url": normalize_device_url(raw_profile["url"])}
+            if isinstance(raw_profile.get("version"), str):
+                profile["version"] = raw_profile["version"]
+            devices[name] = profile
+        current = (
+            parsed.get("current") if isinstance(parsed.get("current"), str) else None
+        )
+        if current not in devices:
+            current = None
+        return {"version": 1, "current": current, "devices": devices}
+
+    def write(self, config: dict[str, Any]) -> None:
+        self.file_path.parent.mkdir(parents=True, exist_ok=True)
+        temporary = self.file_path.with_name(
+            f"{self.file_path.name}.{os.getpid()}.{secrets.token_hex(4)}.tmp"
+        )
+        try:
+            temporary.write_text(
+                json.dumps(config, ensure_ascii=False, indent=2) + "\n",
+                encoding="utf-8",
+            )
+            try:
+                temporary.chmod(0o600)
+            except OSError:
+                pass
+            os.replace(temporary, self.file_path)
+        except OSError as error:
+            temporary.unlink(missing_ok=True)
+            raise CubicError(
+                f"Unable to write config {self.file_path}.", code="CONFIG_ERROR"
+            ) from error
+
+
+def resolve_device(
+    store: ConfigStore,
+    option_host: str | None = None,
+    env: Mapping[str, str] | None = None,
+) -> dict[str, str | None]:
+    values = os.environ if env is None else env
+    if option_host:
+        return {
+            "url": normalize_device_url(option_host),
+            "name": None,
+            "source": "option",
+        }
+    if values.get("CUBIC_HOST"):
+        return {
+            "url": normalize_device_url(values["CUBIC_HOST"]),
+            "name": None,
+            "source": "environment",
+        }
+    config = store.read()
+    current = config["current"]
+    profile = config["devices"].get(current) if current else None
+    if not current or not profile:
+        raise CubicError(
+            "No device selected. Run `cubic-py device add <name> <host>` or pass --host.",
+            code="NO_DEVICE",
+        )
+    return {"url": profile["url"], "name": current, "source": "config"}

holocubic_cli_python/errors.py

@@ -0,0 +1,27 @@
+"""Stable error types shared by the Python client, transfers, and CLI."""
+
+
+class CubicError(Exception):
+    def __init__(
+        self, message: str, *, code: str = "CUBIC_ERROR", exit_code: int = 1
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.exit_code = exit_code
+
+
+class UsageError(CubicError, ValueError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, code="USAGE_ERROR", exit_code=2)
+
+
+class HttpError(CubicError):
+    def __init__(self, message: str, status: int, method: str, path: str) -> None:
+        super().__init__(message, code="NOT_FOUND" if status == 404 else "HTTP_ERROR")
+        self.status = status
+        self.method = method
+        self.path = path
+
+
+def is_not_found(error: BaseException) -> bool:
+    return isinstance(error, HttpError) and error.status == 404