msdev 0.9.0__py3-none-any.whl

msdev/core/workspace/client.py

@@ -0,0 +1,274 @@
+"""Client-side RPC mapping for registered workspaces."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import glob as globlib
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from ..resources import EnvironmentStore, NodeStore
+from ..transport import RpcTransport, SshRpcTransport, UnixRpcTransport
+from .paths import ResolvedPath, normalize_relative
+from .registry import Workspace
+
+
+WorkspaceTransportFactory = Callable[[Workspace], RpcTransport]
+
+
+def transport_for_workspace(
+    workspace: Workspace,
+    *,
+    environment_store: EnvironmentStore | None = None,
+) -> RpcTransport:
+    """Select the daemon transport declared by a workspace."""
+    if workspace.environment == "local":
+        return UnixRpcTransport()
+    environments = environment_store or EnvironmentStore()
+    environment = environments.get(workspace.environment)
+    node = NodeStore(environments.path).get(environment.node)
+    return SshRpcTransport(node, environment)
+
+
+def workspace_params(workspace: Workspace, **values: Any) -> dict[str, Any]:
+    """Build daemon workspace parameters, omitting optional ``None`` values."""
+    params: dict[str, Any] = {"root": workspace.root}
+    params.update({key: value for key, value in values.items() if value is not None})
+    return params
+
+
+def _call_workspace(
+    workspace: Workspace,
+    method: str,
+    params: dict[str, Any],
+    *,
+    environment_store: EnvironmentStore | None,
+    create_transport: WorkspaceTransportFactory | None,
+) -> Any:
+    transport = (
+        create_transport(workspace)
+        if create_transport is not None
+        else transport_for_workspace(
+            workspace,
+            environment_store=environment_store,
+        )
+    )
+    return transport.call(method, params)
+
+
+def _call(
+    resolved: ResolvedPath,
+    method: str,
+    params: dict[str, Any],
+    *,
+    environment_store: EnvironmentStore | None,
+    create_transport: WorkspaceTransportFactory | None,
+) -> Any:
+    return _call_workspace(
+        resolved.workspace,
+        method,
+        params,
+        environment_store=environment_store,
+        create_transport=create_transport,
+    )
+
+
+def stat_path(
+    resolved: ResolvedPath,
+    *,
+    environment_store: EnvironmentStore | None = None,
+    create_transport: WorkspaceTransportFactory | None = None,
+) -> dict[str, Any]:
+    return _call(
+        resolved,
+        "workspace.stat",
+        workspace_params(resolved.workspace, path=resolved.relative),
+        environment_store=environment_store,
+        create_transport=create_transport,
+    )
+
+
+def read_file(
+    resolved: ResolvedPath,
+    *,
+    max_bytes: int = 1024 * 1024,
+    environment_store: EnvironmentStore | None = None,
+    create_transport: WorkspaceTransportFactory | None = None,
+) -> tuple[bytes, dict[str, Any]]:
+    result = _call(
+        resolved,
+        "workspace.read",
+        workspace_params(
+            resolved.workspace,
+            path=resolved.relative,
+            max_bytes=max_bytes,
+        ),
+        environment_store=environment_store,
+        create_transport=create_transport,
+    )
+    try:
+        encoded = result["content_base64"]
+    except (KeyError, TypeError) as exc:
+        raise ValueError("workspace.read returned no base64 content") from exc
+    if not isinstance(encoded, str):
+        raise ValueError("workspace.read returned non-string base64 content")
+    try:
+        content = base64.b64decode(encoded, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise ValueError("workspace.read returned invalid base64 content") from exc
+    if base64.b64encode(content).decode("ascii") != encoded:
+        raise ValueError("workspace.read returned non-canonical base64 content")
+    return content, dict(result)
+
+
+def list_directory(
+    resolved: ResolvedPath,
+    *,
+    environment_store: EnvironmentStore | None = None,
+    create_transport: WorkspaceTransportFactory | None = None,
+) -> dict[str, Any]:
+    return _call(
+        resolved,
+        "workspace.list",
+        workspace_params(resolved.workspace, path=resolved.relative),
+        environment_store=environment_store,
+        create_transport=create_transport,
+    )
+
+
+def _scoped_glob(relative: str, pattern: str) -> str:
+    normalized_pattern = normalize_relative(pattern)
+    if relative == ".":
+        return normalized_pattern
+    if normalized_pattern == ".":
+        return globlib.escape(relative)
+    return f"{globlib.escape(relative)}/{normalized_pattern}"
+
+
+def glob_result(
+    resolved: ResolvedPath,
+    pattern: str,
+    *,
+    max_results: int = 1000,
+    environment_store: EnvironmentStore | None = None,
+    create_transport: WorkspaceTransportFactory | None = None,
+) -> dict[str, Any]:
+    result = _call(
+        resolved,
+        "workspace.glob",
+        workspace_params(
+            resolved.workspace,
+            pattern=_scoped_glob(resolved.relative, pattern),
+            max_results=max_results,
+        ),
+        environment_store=environment_store,
+        create_transport=create_transport,
+    )
+    matches = result.get("matches") if isinstance(result, dict) else None
+    if not isinstance(matches, list):
+        raise ValueError("workspace.glob returned invalid matches")
+    for item in matches:
+        if not isinstance(item, dict) or not isinstance(item.get("path"), str):
+            raise ValueError("workspace.glob returned an invalid match")
+    return dict(result)
+
+
+def search_workspace(
+    workspace: Workspace,
+    pattern: str,
+    *,
+    paths: Sequence[str],
+    glob: str | None = None,
+    max_results: int = 1000,
+    environment_store: EnvironmentStore | None = None,
+    create_transport: WorkspaceTransportFactory | None = None,
+) -> dict[str, Any]:
+    if isinstance(paths, (str, bytes)) or not isinstance(paths, Sequence):
+        raise ValueError("search paths must be a string array")
+    normalized_paths = [normalize_relative(path) for path in paths]
+    result = _call_workspace(
+        workspace,
+        "workspace.search",
+        workspace_params(
+            workspace,
+            pattern=pattern,
+            paths=normalized_paths,
+            glob=glob,
+            max_results=max_results,
+        ),
+        environment_store=environment_store,
+        create_transport=create_transport,
+    )
+    matches = result.get("matches") if isinstance(result, dict) else None
+    if not isinstance(matches, list) or not all(
+        isinstance(item, dict) for item in matches
+    ):
+        raise ValueError("workspace.search returned invalid matches")
+    return dict(result)
+
+
+def write_bytes(
+    resolved: ResolvedPath,
+    content: bytes,
+    *,
+    environment_store: EnvironmentStore | None = None,
+    expected_sha256: str | None = None,
+    create_transport: WorkspaceTransportFactory | None = None,
+) -> dict[str, Any]:
+    if not isinstance(content, bytes):
+        raise TypeError("workspace content must be bytes")
+    return _call(
+        resolved,
+        "workspace.write",
+        workspace_params(
+            resolved.workspace,
+            path=resolved.relative,
+            content_base64=base64.b64encode(content).decode("ascii"),
+            expected_sha256=expected_sha256,
+        ),
+        environment_store=environment_store,
+        create_transport=create_transport,
+    )
+
+
+def delete_path(
+    resolved: ResolvedPath,
+    *,
+    environment_store: EnvironmentStore | None = None,
+    create_transport: WorkspaceTransportFactory | None = None,
+) -> dict[str, Any]:
+    return _call(
+        resolved,
+        "workspace.delete",
+        workspace_params(resolved.workspace, path=resolved.relative),
+        environment_store=environment_store,
+        create_transport=create_transport,
+    )
+
+
+def git_workspace(
+    workspace: Workspace,
+    operation: str,
+    argv: Sequence[str] = (),
+    *,
+    execution_root: str,
+    environment_store: EnvironmentStore | None = None,
+    create_transport: WorkspaceTransportFactory | None = None,
+) -> dict[str, Any]:
+    if operation not in {"status", "diff"}:
+        raise ValueError(f"unsupported workspace Git operation: {operation}")
+    result = _call_workspace(
+        workspace,
+        f"workspace.git_{operation}",
+        workspace_params(
+            workspace,
+            execution_root=execution_root,
+            argv=list(argv),
+        ),
+        environment_store=environment_store,
+        create_transport=create_transport,
+    )
+    if not isinstance(result, dict):
+        raise ValueError("workspace Git operation returned a non-object result")
+    return dict(result)

msdev/core/workspace/paths.py

@@ -0,0 +1,45 @@
+"""Portable workspace-path parsing and normalization."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .registry import Workspace
+
+
+_WINDOWS_ABSOLUTE_RE = re.compile(r"^[A-Za-z]:($|/)")
+
+
+def normalize_relative(path: str) -> str:
+    """Return a normalized workspace-relative POSIX path."""
+    if not isinstance(path, str):
+        raise ValueError("workspace path must be a string")
+    if "\0" in path:
+        raise ValueError("workspace path must not contain NUL")
+
+    portable = path.replace("\\", "/")
+    if portable.startswith("/") or _WINDOWS_ABSOLUTE_RE.match(portable):
+        raise ValueError(f"workspace path must be relative: {path!r}")
+
+    parts: list[str] = []
+    for part in portable.split("/"):
+        if part in {"", "."}:
+            continue
+        if part == "..":
+            raise ValueError(f"workspace path traversal is not allowed: {path!r}")
+        parts.append(part)
+    return "/".join(parts) or "."
+
+
+@dataclass(frozen=True)
+class ResolvedPath:
+    """A normalized relative path paired with its registered workspace."""
+
+    workspace: Workspace
+    relative: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.workspace, Workspace):
+            raise TypeError("workspace must be a Workspace")
+        object.__setattr__(self, "relative", normalize_relative(self.relative))

msdev/core/workspace/registry.py

@@ -0,0 +1,151 @@
+"""Local registry for named execution workspaces."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from ..config import _exclusive_file_lock, config_home
+
+
+WORKSPACE_CONFIG_VERSION = 2
+
+
+@dataclass(frozen=True)
+class Workspace:
+    """A named root in a local or remote msdev environment."""
+
+    name: str
+    environment: str
+    root: str
+    execution_root: str | None = None
+
+    def __post_init__(self) -> None:
+        for field_name in ("name", "environment", "root"):
+            value = getattr(self, field_name)
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(f"workspace {field_name} must be a non-empty string")
+            if "\0" in value:
+                raise ValueError(f"workspace {field_name} must not contain NUL")
+        if self.execution_root is not None:
+            if (
+                not isinstance(self.execution_root, str)
+                or not self.execution_root.strip()
+            ):
+                raise ValueError(
+                    "workspace execution_root must be a non-empty string or None"
+                )
+            if "\0" in self.execution_root:
+                raise ValueError("workspace execution_root must not contain NUL")
+
+
+class WorkspaceStore:
+    """Atomic, versioned JSON-backed workspace registry."""
+
+    def __init__(self, path: Path | None = None):
+        self.path = path or config_home() / "workspaces.json"
+        self.lock_path = self.path.with_name(f".{self.path.name}.lock")
+
+    @staticmethod
+    def _empty() -> dict[str, Any]:
+        return {"version": WORKSPACE_CONFIG_VERSION, "workspaces": {}}
+
+    def load(self) -> dict[str, Any]:
+        if not self.path.exists():
+            return self._empty()
+        try:
+            value = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise ValueError(f"invalid workspace config {self.path}: {exc}") from exc
+        if not isinstance(value, dict):
+            raise ValueError(f"unsupported workspace config schema in {self.path}")
+        if "active" in value:
+            raise ValueError(
+                "global active workspace selection is unsupported; "
+                "remove the 'active' field and name the workspace explicitly"
+            )
+        if (
+            value.get("version") != WORKSPACE_CONFIG_VERSION
+            or not isinstance(value.get("workspaces"), dict)
+        ):
+            raise ValueError(f"unsupported workspace config schema in {self.path}")
+
+        normalized: dict[str, dict[str, Any]] = {}
+        for name, raw in value["workspaces"].items():
+            if not isinstance(name, str) or not isinstance(raw, dict):
+                raise ValueError(f"invalid workspace entry in {self.path}")
+            try:
+                workspace = Workspace(**raw)
+            except (TypeError, ValueError) as exc:
+                raise ValueError(
+                    f"invalid workspace entry {name!r} in {self.path}: {exc}"
+                ) from exc
+            if workspace.name != name:
+                raise ValueError(
+                    f"workspace key {name!r} does not match entry name "
+                    f"{workspace.name!r}"
+                )
+            normalized[name] = asdict(workspace)
+        return {
+            "version": WORKSPACE_CONFIG_VERSION,
+            "workspaces": normalized,
+        }
+
+    def _save(self, value: dict[str, Any]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        fd, temporary_name = tempfile.mkstemp(
+            prefix=".workspaces-",
+            suffix=".json",
+            dir=self.path.parent,
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump(
+                    value,
+                    handle,
+                    ensure_ascii=False,
+                    indent=2,
+                    sort_keys=True,
+                )
+                handle.write("\n")
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temporary_name, self.path)
+        finally:
+            try:
+                os.unlink(temporary_name)
+            except FileNotFoundError:
+                pass
+
+    def add(self, workspace: Workspace, *, force: bool = False) -> None:
+        with _exclusive_file_lock(self.lock_path):
+            value = self.load()
+            if workspace.name in value["workspaces"] and not force:
+                raise ValueError(
+                    f"workspace {workspace.name!r} already exists; "
+                    "use a different name or pass --force"
+                )
+            value["workspaces"][workspace.name] = asdict(workspace)
+            self._save(value)
+
+    def get(self, name: str) -> Workspace:
+        raw = self.load()["workspaces"].get(name)
+        if raw is None:
+            raise KeyError(f"unknown workspace: {name}")
+        return Workspace(**raw)
+
+    def list(self) -> list[Workspace]:
+        values = self.load()["workspaces"]
+        return [Workspace(**values[name]) for name in sorted(values)]
+
+    def remove(self, name: str) -> None:
+        with _exclusive_file_lock(self.lock_path):
+            value = self.load()
+            if name not in value["workspaces"]:
+                raise KeyError(f"unknown workspace: {name}")
+            del value["workspaces"][name]
+            self._save(value)