msdev 0.9.0__py3-none-any.whl

msdev/core/__init__.py

@@ -0,0 +1 @@
+"""msdev core capabilities: nodes, environments, workspaces, and inventory."""

msdev/core/config.py

@@ -0,0 +1,193 @@
+"""Shared local paths, locking, and environment-layer parsing."""
+
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator
+
+try:
+    import fcntl
+except ImportError:  # pragma: no cover - exercised on Windows.
+    fcntl = None  # type: ignore[assignment]
+
+try:
+    import msvcrt
+except ImportError:  # pragma: no cover - exercised on POSIX.
+    msvcrt = None  # type: ignore[assignment]
+
+
+@contextmanager
+def _exclusive_file_lock(path: Path) -> Iterator[None]:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_CLOEXEC", 0)
+    flags |= getattr(os, "O_NOFOLLOW", 0)
+    descriptor = os.open(path, flags, 0o600)
+    try:
+        if fcntl is not None:
+            fcntl.flock(descriptor, fcntl.LOCK_EX)
+        elif msvcrt is not None:  # pragma: no cover - Windows only.
+            if os.fstat(descriptor).st_size == 0:
+                os.write(descriptor, b"\0")
+            os.lseek(descriptor, 0, os.SEEK_SET)
+            msvcrt.locking(descriptor, msvcrt.LK_LOCK, 1)
+        else:  # pragma: no cover
+            raise RuntimeError("no supported interprocess file-lock API")
+        yield
+    finally:
+        if fcntl is not None:
+            fcntl.flock(descriptor, fcntl.LOCK_UN)
+        elif msvcrt is not None:  # pragma: no cover - Windows only.
+            os.lseek(descriptor, 0, os.SEEK_SET)
+            msvcrt.locking(descriptor, msvcrt.LK_UNLCK, 1)
+        os.close(descriptor)
+
+
+def parse_environment_spec(spec: str) -> tuple[str, str]:
+    kind, separator, value = spec.partition(":")
+    kind = kind.strip().lower()
+    value = value.strip()
+    if not separator or kind not in {"conda", "venv", "uv"} or not value:
+        raise ValueError(
+            f"invalid environment {spec!r}; expected "
+            "conda:<name-or-prefix>, venv:<path>, or uv:<project-path>"
+        )
+    return kind, value
+
+
+_CONDA_RUN_SCRIPT = """
+selector=$1
+shift
+conda_bin=$(command -v conda 2>/dev/null || true)
+if [ -z "$conda_bin" ] && [ "${selector#*/}" != "$selector" ]; then
+  candidate=$selector
+  while [ -n "$candidate" ] && [ "$candidate" != "/" ]; do
+    if [ -x "$candidate/bin/conda" ]; then
+      conda_bin=$candidate/bin/conda
+      break
+    fi
+    parent=$(dirname -- "$candidate")
+    [ "$parent" = "$candidate" ] && break
+    candidate=$parent
+  done
+fi
+if [ -z "$conda_bin" ]; then
+  for candidate in \
+    "$HOME/miniconda3/bin/conda" \
+    "$HOME/anaconda3/bin/conda" \
+    "$HOME/miniforge3/bin/conda"; do
+    if [ -x "$candidate" ]; then
+      conda_bin=$candidate
+      break
+    fi
+  done
+fi
+if [ -z "$conda_bin" ]; then
+  echo "conda executable not found for environment: $selector" >&2
+  exit 127
+fi
+case "$selector" in
+  */*) exec "$conda_bin" run --no-capture-output -p "$selector" "$@" ;;
+  *) exec "$conda_bin" run --no-capture-output -n "$selector" "$@" ;;
+esac
+""".strip()
+
+
+def wrap_conda_command(command: list[str], selector: str) -> list[str]:
+    """Run argv in a Conda env even when conda is absent from non-login PATH."""
+    return [
+        "sh",
+        "-c",
+        _CONDA_RUN_SCRIPT,
+        "msdev-conda",
+        selector,
+        *command,
+    ]
+
+
+_CONDA_ACTIVATION_ENV_SCRIPT = """
+selector=$1
+shift
+conda_bin=$(command -v conda 2>/dev/null || true)
+if [ -z "$conda_bin" ] && [ "${selector#*/}" != "$selector" ]; then
+  candidate=$selector
+  while [ -n "$candidate" ] && [ "$candidate" != "/" ]; do
+    if [ -x "$candidate/bin/conda" ]; then
+      conda_bin=$candidate/bin/conda
+      break
+    fi
+    parent=$(dirname -- "$candidate")
+    [ "$parent" = "$candidate" ] && break
+    candidate=$parent
+  done
+fi
+if [ -z "$conda_bin" ]; then
+  for candidate in \
+    "$HOME/miniconda3/bin/conda" \
+    "$HOME/anaconda3/bin/conda" \
+    "$HOME/miniforge3/bin/conda"; do
+    if [ -x "$candidate" ]; then
+      conda_bin=$candidate
+      break
+    fi
+  done
+fi
+if [ -z "$conda_bin" ]; then
+  echo "conda executable not found for environment: $selector" >&2
+  exit 127
+fi
+resolved=$(readlink -f "$conda_bin" 2>/dev/null || printf '%s' "$conda_bin")
+conda_base=$(dirname -- "$(dirname -- "$resolved")")
+conda_sh=$conda_base/etc/profile.d/conda.sh
+if [ ! -r "$conda_sh" ]; then
+  echo "conda activation script not found: $conda_sh" >&2
+  exit 127
+fi
+exec 3>&1
+exec 1>&2
+. "$conda_sh"
+conda activate "$selector"
+exec 1>&3
+exec "$@"
+""".strip()
+
+
+def wrap_conda_activation_command(
+    command: list[str],
+    selector: str,
+) -> list[str]:
+    """Activate Conda through shell functions, then execute argv."""
+    return [
+        "bash",
+        "-c",
+        _CONDA_ACTIVATION_ENV_SCRIPT,
+        "msdev-conda-activate",
+        selector,
+        *command,
+    ]
+
+
+def config_home() -> Path:
+    override = os.environ.get("MSDEV_CONFIG_HOME")
+    if override:
+        return Path(override).expanduser()
+    base = os.environ.get("XDG_CONFIG_HOME")
+    return Path(base).expanduser() / "msdev" if base else Path.home() / ".config" / "msdev"
+
+
+def data_home() -> Path:
+    override = os.environ.get("MSDEV_DATA_HOME")
+    if override:
+        return Path(override).expanduser()
+    base = os.environ.get("XDG_DATA_HOME")
+    return Path(base).expanduser() / "msdevd" if base else Path.home() / ".local" / "share" / "msdevd"
+
+
+def default_socket_path() -> Path:
+    override = os.environ.get("MSDEVD_SOCKET")
+    if override:
+        return Path(override).expanduser()
+    # SSH sessions frequently lack XDG_RUNTIME_DIR while systemd user services
+    # set it to /run/user/<uid>. A stable per-user path keeps both sides aligned.
+    return data_home() / "msdevd.sock"

msdev/core/guides.py

@@ -0,0 +1,100 @@
+"""Private local Markdown guides for nodes and execution environments."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from urllib.parse import quote
+
+from .config import config_home
+
+
+MAX_GUIDE_BYTES = 256 * 1024
+
+
+class ResourceGuideStore:
+    def __init__(self, scope: str, root: Path | None = None):
+        if scope not in {"nodes", "environments"}:
+            raise ValueError(f"unsupported guide scope: {scope}")
+        self.root = root or config_home() / "guides" / scope
+
+    @staticmethod
+    def _filename(resource: str) -> str:
+        if not isinstance(resource, str) or not resource.strip() or "\0" in resource:
+            raise ValueError("resource name must be a non-empty string")
+        return f"{quote(resource, safe='')}.md"
+
+    def path(self, resource: str) -> Path:
+        return self.root / self._filename(resource)
+
+    def read(self, resource: str) -> str | None:
+        path = self.path(resource)
+        try:
+            if path.is_symlink():
+                raise ValueError(f"guide must not be a symlink: {path}")
+            with path.open("rb") as handle:
+                raw = handle.read(MAX_GUIDE_BYTES + 1)
+        except FileNotFoundError:
+            return None
+        if len(raw) > MAX_GUIDE_BYTES:
+            raise ValueError(
+                f"guide exceeds {MAX_GUIDE_BYTES} bytes: {path}"
+            )
+        return raw.decode("utf-8")
+
+    def write_bytes(self, resource: str, raw: bytes) -> Path:
+        if len(raw) > MAX_GUIDE_BYTES:
+            raise ValueError(
+                f"guide exceeds {MAX_GUIDE_BYTES} bytes"
+            )
+        return self.write(resource, raw.decode("utf-8"))
+
+    def write(self, resource: str, content: str) -> Path:
+        raw = content.encode("utf-8")
+        if len(raw) > MAX_GUIDE_BYTES:
+            raise ValueError(
+                f"guide exceeds {MAX_GUIDE_BYTES} bytes"
+            )
+        path = self.path(resource)
+        self.root.mkdir(parents=True, exist_ok=True, mode=0o700)
+        if os.name == "posix":
+            os.chmod(self.root, 0o700)
+        descriptor, temporary = tempfile.mkstemp(
+            prefix=f".{path.name}.",
+            dir=self.root,
+        )
+        try:
+            if os.name == "posix":
+                os.fchmod(descriptor, 0o600)
+            with os.fdopen(descriptor, "wb") as handle:
+                handle.write(raw)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temporary, path)
+            if os.name == "posix":
+                os.chmod(path, 0o600)
+            return path
+        finally:
+            try:
+                os.unlink(temporary)
+            except FileNotFoundError:
+                pass
+
+    def delete(self, resource: str) -> bool:
+        path = self.path(resource)
+        try:
+            path.unlink()
+            return True
+        except FileNotFoundError:
+            return False
+
+
+class NodeGuideStore(ResourceGuideStore):
+    def __init__(self, root: Path | None = None):
+        super().__init__("nodes", root)
+
+
+class EnvironmentGuideStore(ResourceGuideStore):
+    def __init__(self, root: Path | None = None):
+        super().__init__("environments", root)