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

holocubic_cli_python/models.py

@@ -0,0 +1,179 @@
+"""Typed public models for the HoloCubic DevTools API."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+LEGACY_V1_CAPABILITIES = (
+    "fs.list",
+    "fs.stat",
+    "fs.read",
+    "fs.write",
+    "fs.mkdir",
+    "fs.rename",
+    "fs.remove",
+    "fs.rmdir",
+    "apps.list",
+    "devrun.read",
+    "devrun.save",
+    "devrun.run",
+)
+
+
+@dataclass(frozen=True)
+class DeviceInfo:
+    api_version: int
+    version: str | None
+    route_base: str
+    root_path: str
+    chunk_size: int
+    max_file_size: int
+    max_code_bytes: int
+    run_app_id: str
+    run_app_main: str
+    capabilities: tuple[str, ...]
+    raw: dict[str, Any] = field(repr=False)
+
+
+@dataclass(frozen=True)
+class RemoteEntry:
+    name: str
+    path: str
+    size: int
+    is_dir: bool
+    ext: str
+    mime: str
+    category: str
+
+    def public(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "path": self.path,
+            "size": self.size,
+            "isDir": self.is_dir,
+            "ext": self.ext,
+            "mime": self.mime,
+            "category": self.category,
+        }
+
+
+@dataclass(frozen=True)
+class ListResult:
+    path: str
+    parent: str
+    dir_count: int
+    file_count: int
+    total_bytes: int
+    items: tuple[RemoteEntry, ...]
+
+    def public(self) -> dict[str, Any]:
+        return {
+            "path": self.path,
+            "parent": self.parent,
+            "dirCount": self.dir_count,
+            "fileCount": self.file_count,
+            "totalBytes": self.total_bytes,
+            "items": [item.public() for item in self.items],
+        }
+
+
+@dataclass(frozen=True)
+class RemoteStat:
+    path: str
+    name: str
+    parent: str
+    size: int
+    is_dir: bool
+    ext: str
+    mime: str
+    category: str
+
+    def public(self) -> dict[str, Any]:
+        return {
+            "path": self.path,
+            "name": self.name,
+            "parent": self.parent,
+            "size": self.size,
+            "isDir": self.is_dir,
+            "ext": self.ext,
+            "mime": self.mime,
+            "category": self.category,
+        }
+
+
+@dataclass(frozen=True)
+class ReadChunk:
+    data: bytes
+    size: int
+    next_offset: int
+    eof: bool
+    name: str
+    mime: str
+
+
+@dataclass(frozen=True)
+class UploadResult:
+    path: str
+    next_offset: int
+    total: int
+    done: bool
+    size: int
+
+
+@dataclass(frozen=True)
+class AppsResult:
+    apps: tuple[dict[str, Any], ...]
+    current_app_id: str | None
+    run_app_id: str
+    run_app_main: str
+
+    def public(self) -> dict[str, Any]:
+        return {
+            "apps": list(self.apps),
+            "currentAppId": self.current_app_id,
+            "runAppId": self.run_app_id,
+            "runAppMain": self.run_app_main,
+        }
+
+
+@dataclass(frozen=True)
+class DevRunResult:
+    id: str
+    entry: str
+    bytes: int
+    launched: bool
+    rescan_requested: bool
+
+    def public(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "entry": self.entry,
+            "bytes": self.bytes,
+            "launched": self.launched,
+            "rescanRequested": self.rescan_requested,
+        }
+
+
+@dataclass(frozen=True)
+class TransferLimits:
+    max_depth: int = 32
+    max_entries: int = 4096
+    max_download_bytes: int = 128 * 1024 * 1024
+
+
+@dataclass(frozen=True)
+class TransferSummary:
+    source: str
+    destination: str
+    files: int
+    directories: int
+    bytes: int
+
+    def public(self) -> dict[str, Any]:
+        return {
+            "source": self.source,
+            "destination": self.destination,
+            "files": self.files,
+            "directories": self.directories,
+            "bytes": self.bytes,
+        }

holocubic_cli_python/remote_path.py

@@ -0,0 +1,62 @@
+"""Remote and local path confinement helpers."""
+
+import os
+import posixpath
+from pathlib import Path, PurePosixPath
+
+from .errors import UsageError
+
+
+REMOTE_ROOT = "/sd"
+
+
+def _reject_nul(value: str) -> None:
+    if "\0" in value:
+        raise UsageError("Remote path contains an invalid NUL character.")
+
+
+def normalize_remote_path(value: str | None, root: str = REMOTE_ROOT) -> str:
+    candidate_value = (value or "").strip()
+    _reject_nul(candidate_value)
+    unix = candidate_value.replace("\\", "/")
+    candidate = unix if unix.startswith("/") else posixpath.join(root, unix or ".")
+    normalized = posixpath.normpath(candidate)
+    if normalized != root and not normalized.startswith(f"{root}/"):
+        raise UsageError(f"Remote path must stay below {root}: {value or ''}")
+    return normalized
+
+
+def remote_join(parent: str, name: str) -> str:
+    _reject_nul(name)
+    if not name or name in {".", ".."} or "/" in name or "\\" in name:
+        raise UsageError(f"Invalid remote entry name: {name}")
+    return normalize_remote_path(posixpath.join(normalize_remote_path(parent), name))
+
+
+def remote_basename(remote_path: str) -> str:
+    normalized = normalize_remote_path(remote_path)
+    return "sd" if normalized == REMOTE_ROOT else posixpath.basename(normalized)
+
+
+def assert_can_delete_remote(remote_path: str) -> None:
+    if normalize_remote_path(remote_path) == REMOTE_ROOT:
+        raise UsageError(f"Refusing to delete {REMOTE_ROOT}.")
+
+
+def safe_local_destination(root: str | Path, relative_path: str) -> Path:
+    _reject_nul(relative_path)
+    normalized = relative_path.replace("\\", "/")
+    pure = PurePosixPath(normalized)
+    if pure.is_absolute() or ".." in pure.parts:
+        raise UsageError(f"Download entry escapes destination: {relative_path}")
+    resolved_root = Path(root).resolve()
+    resolved = (resolved_root / Path(*pure.parts)).resolve()
+    try:
+        common = os.path.commonpath((resolved_root, resolved))
+    except ValueError as error:
+        raise UsageError(
+            f"Download entry escapes destination: {relative_path}"
+        ) from error
+    if Path(common) != resolved_root:
+        raise UsageError(f"Download entry escapes destination: {relative_path}")
+    return resolved