codecraftai-interop-vmworkstation 1.2.0__py3-none-any.whl

ccai/interop/vmworkstation/__init__.py

@@ -0,0 +1,49 @@
+"""
+    .. module:: vmworkstation
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Public exports for the VMware Workstation interop client.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+from ccai.interop.vmworkstation.aspectsvmworkstation import (
+    AspectsVMWorkstation,
+    DEFAULT_VMWORKSTATION_ASPECTS,
+)
+from ccai.interop.vmworkstation.exceptions import (
+    VMWorkstationError,
+    VMRunCommandError,
+    VMWorkstationParseError,
+)
+from ccai.interop.vmworkstation.guestcredential import GuestCredential
+from ccai.interop.vmworkstation.redaction import redact_argv
+from ccai.interop.vmworkstation.results import (
+    GuestExecResult,
+    ToolsState,
+    VMWorkstationActionResult,
+    VMWorkstationActionStatus,
+)
+from ccai.interop.vmworkstation.snapshots import SnapshotRecord
+from ccai.interop.vmworkstation.vmworkstationclient import VMWorkstationClient
+
+
+__all__ = [
+    "AspectsVMWorkstation",
+    "DEFAULT_VMWORKSTATION_ASPECTS",
+    "GuestCredential",
+    "GuestExecResult",
+    "redact_argv",
+    "SnapshotRecord",
+    "ToolsState",
+    "VMRunCommandError",
+    "VMWorkstationActionResult",
+    "VMWorkstationActionStatus",
+    "VMWorkstationClient",
+    "VMWorkstationError",
+    "VMWorkstationParseError",
+]

ccai/interop/vmworkstation/aspectsvmworkstation.py

@@ -0,0 +1,48 @@
+"""
+    .. module:: aspectsvmworkstation
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Behaviour-modifying parameters for the VMware Workstation
+                   interop client.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+from dataclasses import dataclass
+from typing import Optional
+
+from ccai.aspects.aspects import Aspects
+
+
+@dataclass
+class AspectsVMWorkstation(Aspects):
+    """
+        Workstation-specific behaviour carrier.
+
+        Inherits the generic completion / timeout / attempt fields from
+        :class:`Aspects` and adds the small set of behaviour controls the
+        ``vmrun`` dispatcher honours.
+
+        :param elevated: When True, the runner is invoked with ``elevated``.
+        :param raise_on_failure: When True, non-zero ``vmrun`` exits raise a
+            :class:`VMRunCommandError` instead of returning a ``FAILED``
+            result.
+        :param command_timeout: Per-invocation timeout passed through to the
+            runner. ``None`` means no enforced timeout at the runner.
+    """
+    elevated: bool = False
+    raise_on_failure: bool = False
+    command_timeout: Optional[float] = None
+
+
+DEFAULT_VMWORKSTATION_ASPECTS = AspectsVMWorkstation()
+
+
+__all__ = [
+    "AspectsVMWorkstation",
+    "DEFAULT_VMWORKSTATION_ASPECTS",
+]

ccai/interop/vmworkstation/exceptions.py

@@ -0,0 +1,79 @@
+"""
+    .. module:: exceptions
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Typed exceptions raised by the VMware Workstation interop
+                   client.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+from typing import Optional
+
+
+class VMWorkstationError(Exception):
+    """
+        Base class for all VMware Workstation interop errors.
+    """
+
+
+class VMRunCommandError(VMWorkstationError):
+    """
+        Raised when a ``vmrun`` invocation exits non-zero and the caller has
+        opted into exception-on-failure behaviour.
+
+        :param message: Human-readable failure description.
+        :param exit_code: The ``vmrun`` exit code, when available.
+        :param stdout: Captured stdout, when available.
+        :param stderr: Captured stderr, when available.
+        :param command: The argv that was dispatched, when available.
+    """
+
+    def __init__(
+        self,
+        *,
+        message: str,
+        exit_code: Optional[int],
+        stdout: Optional[str],
+        stderr: Optional[str],
+        command: Optional[list],
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.exit_code = exit_code
+        self.stdout = stdout
+        self.stderr = stderr
+        self.command = command
+        return
+
+
+class VMWorkstationParseError(VMWorkstationError):
+    """
+        Raised when ``vmrun`` output cannot be parsed into the expected
+        structure.
+
+        :param message: Human-readable description of the parse failure.
+        :param raw_output: The raw output that could not be parsed.
+    """
+
+    def __init__(
+        self,
+        *,
+        message: str,
+        raw_output: Optional[str],
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.raw_output = raw_output
+        return
+
+
+__all__ = [
+    "VMRunCommandError",
+    "VMWorkstationError",
+    "VMWorkstationParseError",
+]

ccai/interop/vmworkstation/guestcredential.py

@@ -0,0 +1,31 @@
+"""
+    .. module:: guestcredential
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Guest credential carrier for ``vmrun`` guest-exec verbs.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+from dataclasses import dataclass
+
+
+@dataclass
+class GuestCredential:
+    """
+        Username/password pair passed to ``vmrun -gu/-gp`` for guest-exec
+        verbs (``runProgramInGuest``, ``copyFileFromHostToGuest``,
+        ``copyFileFromGuestToHost``).
+
+        :param username: Guest OS username.
+        :param password: Guest OS password.
+    """
+    username: str
+    password: str
+
+
+__all__ = ["GuestCredential"]

ccai/interop/vmworkstation/redaction.py

@@ -0,0 +1,62 @@
+"""
+    .. module:: redaction
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Argv redaction helpers for the VMware Workstation interop
+                   client.
+
+    The ``vmrun`` guest-exec subcommands accept the guest password on the
+    command line via the ``-gp`` flag. The real argv must carry the
+    plaintext password so the command can actually execute, but any copy of
+    that argv that is stored on a result object, embedded in an exception,
+    or written to a log must have the secret scrubbed.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+from typing import List, Optional
+
+
+_REDACTED_PLACEHOLDER = "<redacted>"
+_SECRET_FLAGS = ("-gp",)
+
+
+def redact_argv(*, argv: Optional[List[str]]) -> Optional[List[str]]:
+    """
+        Return a copy of ``argv`` with the value following any secret flag
+        (currently ``-gp``, the guest password) replaced by a redaction
+        placeholder.
+
+        The original list is never mutated; the real argv used for dispatch
+        is left intact.
+
+        :param argv: The argv to redact, or ``None``.
+
+        :returns: A redacted copy of ``argv``, or ``None`` when ``argv`` is
+            ``None``.
+    """
+    if argv is None:
+        rtnval: Optional[List[str]] = None
+        return rtnval
+
+    redacted: List[str] = []
+    redact_next = False
+    for token in argv:
+        if redact_next is True:
+            redacted.append(_REDACTED_PLACEHOLDER)
+            redact_next = False
+            continue
+
+        redacted.append(token)
+        if token in _SECRET_FLAGS:
+            redact_next = True
+
+    rtnval = redacted
+    return rtnval
+
+
+__all__ = ["redact_argv"]

ccai/interop/vmworkstation/results.py

@@ -0,0 +1,81 @@
+"""
+    .. module:: results
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Result types for the VMware Workstation interop client.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import List, Optional
+
+
+class VMWorkstationActionStatus(Enum):
+    """
+        Status enumeration for ``vmrun`` action results.
+    """
+    SUCCESS = "success"
+    FAILED = "failed"
+    DRY_RUN = "dry_run"
+
+
+class ToolsState(Enum):
+    """
+        VMware Tools state as reported by ``vmrun checkToolsState``.
+    """
+    INSTALLED = "installed"
+    RUNNING = "running"
+    NOT_INSTALLED = "not_installed"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class VMWorkstationActionResult:
+    """
+        Result of a ``vmrun`` action invocation.
+
+        :param status: The outcome status.
+        :param detail: Free-form description of the action context.
+        :param exit_code: The ``vmrun`` exit code, when available.
+        :param stdout: Captured stdout, when available.
+        :param stderr: Captured stderr, when available.
+        :param command: The argv that was dispatched, when available.
+    """
+    status: VMWorkstationActionStatus
+    detail: Optional[str]
+    exit_code: Optional[int]
+    stdout: Optional[str]
+    stderr: Optional[str]
+    command: Optional[List[str]]
+
+
+@dataclass
+class GuestExecResult:
+    """
+        Result of a guest-exec ``vmrun`` invocation.
+
+        :param status: The outcome status.
+        :param exit_code: The ``vmrun`` exit code, when available.
+        :param stdout: Captured stdout, when available.
+        :param stderr: Captured stderr, when available.
+        :param command: The argv that was dispatched, when available.
+    """
+    status: VMWorkstationActionStatus
+    exit_code: Optional[int]
+    stdout: Optional[str]
+    stderr: Optional[str]
+    command: Optional[List[str]]
+
+
+__all__ = [
+    "GuestExecResult",
+    "ToolsState",
+    "VMWorkstationActionResult",
+    "VMWorkstationActionStatus",
+]

ccai/interop/vmworkstation/snapshots.py

@@ -0,0 +1,180 @@
+"""
+    .. module:: snapshots
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: ``vmrun listSnapshots`` parsing and the
+                   :class:`SnapshotRecord` data class.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+import os
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+from ccai.interop.vmworkstation.exceptions import VMWorkstationParseError
+
+
+@dataclass
+class SnapshotRecord:
+    """
+        Record describing one snapshot reported by ``vmrun listSnapshots``.
+
+        :param name: The snapshot name (as printed by ``vmrun``).
+        :param parent: The parent snapshot name, or ``None`` for top-level.
+    """
+    name: str
+    parent: Optional[str]
+
+
+def parse_list_snapshots(*, payload: str) -> List[SnapshotRecord]:
+    """
+        Parse the stdout of ``vmrun listSnapshots <vmx>``.
+
+        ``vmrun listSnapshots`` typically prints::
+
+            Total snapshots: <n>
+            <name1>
+            <name2>
+            ...
+
+        Snapshot trees are presented as flat names; parent linkage is not
+        available from the ``listSnapshots`` plain form, so :attr:`parent`
+        is always ``None``.
+
+        :param payload: The decoded stdout from ``vmrun``.
+
+        :returns: A list of :class:`SnapshotRecord`, possibly empty.
+        :raises VMWorkstationParseError: When the header line cannot be
+            located or the declared count does not match the body.
+    """
+    if payload is None:
+        text = ""
+    else:
+        text = payload
+
+    raw_lines = text.splitlines()
+    stripped_lines: List[str] = []
+    for raw in raw_lines:
+        stripped = raw.strip()
+        if len(stripped) > 0:
+            stripped_lines.append(stripped)
+
+    if len(stripped_lines) == 0:
+        rtnval: List[SnapshotRecord] = []
+        return rtnval
+
+    header = stripped_lines[0]
+    lower_header = header.lower()
+    if lower_header.startswith("total snapshots:") is False:
+        err_msg_lines = ["Unexpected 'vmrun listSnapshots' header."]
+        err_msg_lines.append("    HEADER: {!r}".format(header))
+        err_msg = os.linesep.join(err_msg_lines)
+        raise VMWorkstationParseError(message=err_msg, raw_output=text)
+
+    count_text = header.split(":", 1)[1].strip()
+    try:
+        declared_count = int(count_text)
+    except ValueError:
+        err_msg_lines = ["Unable to parse snapshot count."]
+        err_msg_lines.append("    COUNT_TEXT: {!r}".format(count_text))
+        err_msg = os.linesep.join(err_msg_lines)
+        raise VMWorkstationParseError(
+            message=err_msg, raw_output=text,
+        ) from None
+
+    body_lines = stripped_lines[1:]
+    if len(body_lines) != declared_count:
+        err_msg_lines = [
+            "Snapshot count mismatch between header and body.",
+        ]
+        err_msg_lines.append("    DECLARED: {}".format(declared_count))
+        err_msg_lines.append("    ACTUAL: {}".format(len(body_lines)))
+        err_msg = os.linesep.join(err_msg_lines)
+        raise VMWorkstationParseError(message=err_msg, raw_output=text)
+
+    records: List[SnapshotRecord] = []
+    for body in body_lines:
+        record = SnapshotRecord(name=body, parent=None)
+        records.append(record)
+
+    rtnval = records
+    return rtnval
+
+
+def parse_list_running(*, payload: str) -> List[str]:
+    """
+        Parse the stdout of ``vmrun list``.
+
+        ``vmrun list`` prints::
+
+            Total running VMs: <n>
+            <vmx_path_1>
+            <vmx_path_2>
+            ...
+
+        :param payload: The decoded stdout from ``vmrun``.
+
+        :returns: A list of VMX paths, possibly empty.
+        :raises VMWorkstationParseError: When the header line cannot be
+            located or the declared count does not match the body.
+    """
+    if payload is None:
+        text = ""
+    else:
+        text = payload
+
+    raw_lines = text.splitlines()
+    stripped_lines: List[str] = []
+    for raw in raw_lines:
+        stripped = raw.strip()
+        if len(stripped) > 0:
+            stripped_lines.append(stripped)
+
+    if len(stripped_lines) == 0:
+        rtnval: List[str] = []
+        return rtnval
+
+    header = stripped_lines[0]
+    lower_header = header.lower()
+    if lower_header.startswith("total running vms:") is False:
+        err_msg_lines = ["Unexpected 'vmrun list' header."]
+        err_msg_lines.append("    HEADER: {!r}".format(header))
+        err_msg = os.linesep.join(err_msg_lines)
+        raise VMWorkstationParseError(message=err_msg, raw_output=text)
+
+    count_text = header.split(":", 1)[1].strip()
+    try:
+        declared_count = int(count_text)
+    except ValueError:
+        err_msg_lines = ["Unable to parse running VM count."]
+        err_msg_lines.append("    COUNT_TEXT: {!r}".format(count_text))
+        err_msg = os.linesep.join(err_msg_lines)
+        raise VMWorkstationParseError(
+            message=err_msg, raw_output=text,
+        ) from None
+
+    body_lines = stripped_lines[1:]
+    if len(body_lines) != declared_count:
+        err_msg_lines = [
+            "Running VM count mismatch between header and body.",
+        ]
+        err_msg_lines.append("    DECLARED: {}".format(declared_count))
+        err_msg_lines.append("    ACTUAL: {}".format(len(body_lines)))
+        err_msg = os.linesep.join(err_msg_lines)
+        raise VMWorkstationParseError(message=err_msg, raw_output=text)
+
+    rtnval = list(body_lines)
+    return rtnval
+
+
+__all__ = [
+    "SnapshotRecord",
+    "parse_list_running",
+    "parse_list_snapshots",
+]