marsh-lib 0.3.2__tar.gz → 0.3.4__tar.gz

{marsh_lib-0.3.2 → marsh_lib-0.3.4}/.circleci/config.yml

@@ -86,7 +86,7 @@ jobs:
             command -v uv
       - run:
           name: Install dependencies
-          command: uv sync --all-groups
+          command: uv sync --all-groups --extra docker --extra ssh
       - run:
           name: Validate dependency and platform contract
           command: |
@@ -97,9 +97,14 @@ jobs:
 
             assert sys.version_info[:2] == (3, 12), sys.version
             project = tomllib.loads(Path("pyproject.toml").read_text())["project"]
-            assert "optional-dependencies" not in project, "Unexpected optional dependency surface"
+            extras = project["optional-dependencies"]
+            dependencies = project["dependencies"]
+            assert not any(dep.startswith("docker") for dep in dependencies)
+            assert not any(dep.startswith("fabric") for dep in dependencies)
+            assert any(dep.startswith("docker") for dep in extras["docker"])
+            assert any(dep.startswith("fabric") for dep in extras["ssh"])
             assert project["requires-python"] == ">=3.10,<3.13"
-            print("Python 3.12 integration environment validated; optional dependency surface is N/A.")
+            print("Python 3.12 integration environment and optional provider dependency contract validated.")
             PY
       - run:
           name: Pull Docker integration test images
@@ -108,7 +113,9 @@ jobs:
             docker pull ubuntu:24.04
       - run:
           name: Run Docker integration tests
-          command: uv run pytest -vv --disable-warnings --tb=short tests/docker
+          command: |
+            uv run pytest -vv --disable-warnings --tb=short tests/docker
+            uv run pytest -vv --disable-warnings --tb=short tests/core/test_provider_architecture_v034.py::test_docker_provider_executes_real_container
       - run:
           name: Run SSH integration tests
           command: uv run pytest -vv --disable-warnings --tb=short tests/ssh

{marsh_lib-0.3.2 → marsh_lib-0.3.4}/.github/pull_request_template.md

@@ -1,3 +1,6 @@
+## Summary
+[1–3 concise, user-facing bullets describing what changed and why. This section is used in release notes.]
+
 ## Description
 [Brief and concise description of the changes]
 
@@ -17,7 +20,6 @@
 - [ ] Related API documentation, if any, has been updated.
 - [ ] My code is self-documented with clear comments for complex areas.
 - [ ] Public methods and classes include appropriate docstrings.
-- [ ] Function names, variables, and class names are descriptive and adhere to naming conventions.
 - [ ] I understand that pull requests will not be merged if they do not pass the automated tests.
 - [ ] New functionality is covered by automated tests.
 - [ ] Code changes have been tested across relevant environments or configurations.

{marsh_lib-0.3.2 → marsh_lib-0.3.4}/.github/workflows/release.yml

@@ -127,8 +127,20 @@ jobs:
               ],
               "ignore_labels": ["wip", "do-not-merge"],
               "sort": {"order": "ASC", "on_property": "mergedAt"},
+              "custom_placeholders": [
+                {
+                  "name": "SUMMARY",
+                  "source": "BODY",
+                  "transformer": {
+                    "pattern": "^[\\s\\S]*?## Summary\\s*\\n([\\s\\S]*?)(?:\\n## |$)",
+                    "target": "$1",
+                    "flags": "g",
+                    "on_empty": ""
+                  }
+                }
+              ],
               "template": "# Release Notes for #{{TO_TAG}}\n\n#{{CHANGELOG}}\n\n<details>\n<summary>Uncategorized</summary>\n\n#{{UNCATEGORIZED}}\n</details>",
-              "pr_template": "- #{{TITLE}} ([#{{NUMBER}}](#{{URL}})) by @#{{AUTHOR}}"
+              "pr_template": "- #{{TITLE}}\n  #{{SUMMARY}}\n  ([#{{NUMBER}}](#{{URL}})) by @#{{AUTHOR}}"
             }
           fetchReleaseInformation: true
           token: ${{ secrets.GITHUB_TOKEN }}

{marsh_lib-0.3.2 → marsh_lib-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: marsh-lib
-Version: 0.3.2
+Version: 0.3.4
 Summary: Lightweight, extensible Python library for building, managing, and executing command workflows.
 Project-URL: Repository, https://github.com/CedricAnover/marsh
 Author-email: Cedric Anover <cedric.anover@hotmail.com>
@@ -21,8 +21,10 @@ Classifier: Topic :: System :: System Shells
 Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: Utilities
 Requires-Python: <3.13,>=3.10
-Requires-Dist: docker<8.0.0,>=7.1.0
-Requires-Dist: fabric<4.0.0,>=3.2.2
+Provides-Extra: docker
+Requires-Dist: docker<8.0.0,>=7.1.0; extra == 'docker'
+Provides-Extra: ssh
+Requires-Dist: fabric<4.0.0,>=3.2.2; extra == 'ssh'
 Description-Content-Type: text/markdown
 
 # Marsh

marsh_lib-0.3.4/docs/architecture.md

@@ -0,0 +1,86 @@
+# Marsh Architecture
+
+## Architecture
+
+Marsh is moving toward a small execution kernel with explicit boundaries:
+
+```mermaid
+flowchart TD
+    A[UX / Python API] --> B[Workflow / Task]
+    B --> C[Validation]
+    C --> D[Planning]
+    D --> E[Scheduler]
+    E --> F[Machine / Process]
+    F --> G[Result]
+```
+
+The architectural goal is to keep:
+
+- workflow intent;
+- execution mechanisms;
+- machines;
+- processes;
+- scheduling;
+- policies;
+- providers;
+- observability; and
+- results
+
+as distinct concepts.
+
+The existing command and DAG APIs remain useful low-level building blocks and compatibility surfaces.
+
+## Implementation status
+
+This document describes the architecture implemented by the current Alpha release. Future capabilities are described only as extension boundaries and are not presented as implemented features.
+
+
+## Provider boundary (v0.3.4)
+
+Providers are execution-mechanism adapters. Workflow intent, planning, scheduling, and policy semantics remain provider-independent.
+
+```mermaid
+classDiagram
+    Workflow --> ExecutionPlan
+    ExecutionPlan --> Scheduler
+    Scheduler --> Machine
+    Machine --> Process
+    Process --> Result
+    Workflow --> ProviderRegistry
+    ProviderRegistry --> Provider
+    ProviderConfig --> ProviderRegistry
+    Provider --> Machine
+    Provider --> Result
+
+    class Provider {
+        <<protocol>>
+        +capabilities
+        +create_machine()
+    }
+    class ProviderConfig {
+        +name
+        +options
+    }
+    class ProviderRegistry {
+        +register()
+        +resolve()
+        +find()
+    }
+    class LocalProvider
+    class DockerProvider
+    Provider <|.. LocalProvider
+    Provider <|.. DockerProvider
+```
+
+Runtime resolution is deliberately outside the Workflow IR:
+
+```text
+execute_workflow(workflow, provider=config)
+    -> resolve config.name in ProviderRegistry
+    -> verify required capabilities
+    -> materialize Provider Machine
+    -> run the existing Scheduler
+    -> return the existing Result model
+```
+
+A new backend should therefore add a Provider/Adapter and conformance tests rather than introduce provider-specific branching into Workflow or planning.

marsh_lib-0.3.4/docs/releases/v0.3.3.md

@@ -0,0 +1,33 @@
+# v0.3.3 — Kernel Contract Stabilization
+
+## Summary
+
+v0.3.3 stabilizes the smallest Marsh execution kernel before further provider and concurrency work.
+
+## Contract changes
+
+- `plan_workflow()` is the canonical dependency-planning semantic owner.
+- `validate_workflow()` delegates to canonical planning instead of maintaining a second topological implementation.
+- Deterministic task order and initial readiness are regression-tested.
+- Scheduler and Machine replacement are covered by conformance tests.
+- Lifecycle, failure, timeout, cancellation, dependency-skip, and fail-fast semantics are regression-tested.
+- Modern namespace compatibility remains covered without removing legacy APIs.
+- Observer failures remain non-authoritative and cannot change execution outcomes.
+
+## Reliability fix
+
+- Hardened Docker container cleanup against auto-remove races that can surface as stale-container `404 Not Found` errors.
+
+## Verification
+
+- CircleCI: Python 3.10, 3.11, 3.12
+- CircleCI: lint and wheel build
+- CircleCI: Docker integration
+- CircleCI: SSH integration
+- GitHub Actions: Linux test/coverage
+- GitHub Actions: native Windows portability
+- GitHub Actions: Docker integration smoke
+
+## Scope guardrails
+
+No new runtime dependency, concurrency engine, remote execution model, workflow IR expansion, or provider architecture expansion was introduced in this release.

{marsh_lib-0.3.2 → marsh_lib-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "marsh-lib"
-version = "0.3.2"
+version = "0.3.4"
 description = "Lightweight, extensible Python library for building, managing, and executing command workflows."
 authors = [{ name = "Cedric Anover", email = "cedric.anover@hotmail.com" }]
 license = { text = "MIT" }
@@ -26,10 +26,15 @@ classifiers = [
     "Operating System :: Microsoft :: Windows",
     "Operating System :: POSIX :: Linux",
 ]
-dependencies = [
-    "fabric>=3.2.2,<4.0.0",
+dependencies = []
+
+[project.optional-dependencies]
+docker = [
     "docker>=7.1.0,<8.0.0",
 ]
+ssh = [
+    "fabric>=3.2.2,<4.0.0",
+]
 
 [project.urls]
 Repository = "https://github.com/CedricAnover/marsh"
@@ -42,6 +47,8 @@ dev = [
     "fabric[pytest]>=3.2.2,<4.0.0",
 ]
 test = [
+    "docker>=7.1.0,<8.0.0",
+    "fabric[pytest]>=3.2.2,<4.0.0",
     "pytest>=8.3.2,<9.0.0",
     "pytest-mock>=3.14.0,<4.0.0",
     "testcontainers>=4.9.0,<5.0.0",
@@ -78,3 +85,9 @@ line-length = 88
 target-version = ['py310', 'py311', 'py312', 'py313']
 include = '\.pyi?$'
 #extend-exclude = '...'
+
+
+[tool.pytest.ini_options]
+markers = [
+    "integration: requires external runtime services such as Docker or SSH",
+]

marsh_lib-0.3.4/src/marsh/__init__.py

@@ -0,0 +1,9 @@
+from marsh.core import *
+
+
+def __getattr__(name):
+    if name == "ssh":
+        import importlib
+
+        return importlib.import_module("marsh.ssh")
+    raise AttributeError(name)

{marsh_lib-0.3.2 → marsh_lib-0.3.4}/src/marsh/core/__init__.py

@@ -19,6 +19,16 @@ from marsh.core.serialization import (
 
 from marsh.core.runtime import ExecutionPlan, LocalMachine, LocalProcess, SequentialScheduler, execute_workflow, plan_workflow
 from marsh.core.policies import ExecutionPolicy, FailurePolicy, ResourcePolicy, RetryPolicy, TimeoutPolicy
-from marsh.core.providers import LocalProvider, ProviderCapabilities, ProviderRegistry, UnsupportedCapabilityError
+from marsh.core.providers import (
+    LocalProvider,
+    Provider,
+    ProviderCapabilities,
+    ProviderConfig,
+    ProviderConfigurationError,
+    ProviderError,
+    ProviderRegistry,
+    ProviderUnavailableError,
+    UnsupportedCapabilityError,
+)
 from marsh.core.cache import Cache, CachePolicy, MemoryCache, cache_key_for_task
 from marsh.core.observability import EventType, Observer, RuntimeEvent, emit_event

{marsh_lib-0.3.2 → marsh_lib-0.3.4}/src/marsh/core/providers.py

@@ -1,15 +1,26 @@
-"""Provider discovery and capability negotiation for Marsh."""
+"""Provider discovery, configuration, and capability negotiation for Marsh."""
 
 from __future__ import annotations
 
 from dataclasses import dataclass
 from typing import Iterable, Mapping, Protocol, runtime_checkable
 
-from marsh.core.domain import Machine, ProcessSpec
-from marsh.core.runtime import LocalMachine
+from marsh.core.domain import Machine
 
 
-class UnsupportedCapabilityError(ValueError):
+class ProviderError(RuntimeError):
+    """Base error for provider-boundary failures."""
+
+
+class ProviderConfigurationError(ProviderError, ValueError):
+    """Raised for invalid provider configuration."""
+
+
+class ProviderUnavailableError(ProviderError):
+    """Raised when a configured provider cannot be reached."""
+
+
+class UnsupportedCapabilityError(ProviderError, ValueError):
     """Raised when a provider cannot satisfy a required capability."""
 
 
@@ -35,6 +46,21 @@ class ProviderCapabilities:
         return set(required).issubset(self.values)
 
 
+@dataclass(frozen=True)
+class ProviderConfig:
+    """Provider selection/configuration without provider-specific semantics."""
+
+    name: str
+    options: Mapping[str, object]
+
+    def __init__(self, name: str, options: Mapping[str, object] | None = None):
+        normalized = name.strip()
+        if not normalized:
+            raise ProviderConfigurationError("provider name must be non-empty")
+        object.__setattr__(self, "name", normalized)
+        object.__setattr__(self, "options", dict(options or {}))
+
+
 @runtime_checkable
 class Provider(Protocol):
     """Mechanism boundary for materializing execution machines."""
@@ -68,14 +94,18 @@ class LocalProvider:
             }
         )
 
-    def create_machine(self, **kwargs) -> LocalMachine:
+    def create_machine(self, **kwargs) -> Machine:
+        from marsh.core.runtime import LocalMachine
+
         if kwargs:
-            raise TypeError(f"unsupported local provider options: {sorted(kwargs)}")
+            raise ProviderConfigurationError(
+                f"unsupported local provider options: {sorted(kwargs)}"
+            )
         return LocalMachine()
 
 
 class ProviderRegistry:
-    """Named provider registry with explicit capability negotiation."""
+    """Deterministic named provider registry with capability negotiation."""
 
     def __init__(self, providers: Mapping[str, Provider] | None = None):
         self._providers: dict[str, Provider] = {}
@@ -83,15 +113,19 @@ class ProviderRegistry:
             self.register(name, provider)
 
     def register(self, name: str, provider: Provider) -> None:
-        name = name.strip()
-        if not name:
-            raise ValueError("provider name must be non-empty")
-        if name in self._providers:
-            raise ValueError(f"provider {name!r} is already registered")
-        self._providers[name] = provider
+        config_name = name.strip()
+        if not config_name:
+            raise ProviderConfigurationError("provider name must be non-empty")
+        if config_name in self._providers:
+            raise ProviderConfigurationError(
+                f"provider {config_name!r} is already registered"
+            )
+        if not isinstance(provider, Provider):
+            raise TypeError("provider does not satisfy the Provider contract")
+        self._providers[config_name] = provider
 
     def get(self, name: str) -> Provider | None:
-        return self._providers.get(name)
+        return self._providers.get(name.strip())
 
     def find(self, capabilities: Iterable[str] = ()) -> tuple[tuple[str, Provider], ...]:
         required = frozenset(capabilities)
@@ -101,8 +135,12 @@ class ProviderRegistry:
             if self._providers[name].capabilities.satisfies(required)
         )
 
-    def require(self, name: str, capabilities: Iterable[str] = ()) -> Provider:
-        provider = self._providers.get(name)
+    def require(
+        self,
+        name: str,
+        capabilities: Iterable[str] = (),
+    ) -> Provider:
+        provider = self.get(name)
         if provider is None:
             raise KeyError(name)
         required = frozenset(capabilities)
@@ -112,3 +150,10 @@ class ProviderRegistry:
                 f"provider {name!r} does not support capabilities: {', '.join(missing)}"
             )
         return provider
+
+    def resolve(
+        self,
+        config: ProviderConfig,
+        capabilities: Iterable[str] = (),
+    ) -> Provider:
+        return self.require(config.name, capabilities)

{marsh_lib-0.3.2 → marsh_lib-0.3.4}/src/marsh/core/runtime.py

@@ -21,6 +21,21 @@ from marsh.core.observability import EventType, Observer, RuntimeEvent, emit_eve
 from marsh.core.policies import ExecutionPolicy
 
 
+class _LocalProvider:
+    """Lazy local provider used only for runtime compatibility."""
+
+    @property
+    def capabilities(self):
+        from marsh.core.providers import LocalProvider
+
+        return LocalProvider().capabilities
+
+    def create_machine(self):
+        from marsh.core.providers import LocalProvider
+
+        return LocalProvider().create_machine()
+
+
 @dataclass(frozen=True)
 class ExecutionPlan:
     """Deterministic workflow order plus tasks initially ready to run."""
@@ -317,9 +332,20 @@ def execute_workflow(
     policy: ExecutionPolicy | None = None,
     observers: tuple[Observer, ...] = (),
     cache: Cache | None = None,
+    provider=None,
+    provider_registry=None,
 ) -> dict[str, Result]:
-    """Execute a workflow sequentially with explicit, composable policies."""
-    machine = machine or LocalMachine()
+    """Execute a workflow sequentially through a selected execution provider."""
+    if machine is not None and provider is not None:
+        raise ValueError("machine and provider cannot both be supplied")
+    if provider is not None:
+        from marsh.core.providers import ProviderConfig, ProviderRegistry
+
+        registry = provider_registry or ProviderRegistry({"local": _LocalProvider()})
+        config = provider if isinstance(provider, ProviderConfig) else ProviderConfig(str(provider))
+        machine = registry.resolve(config).create_machine(**dict(config.options))
+    else:
+        machine = machine or LocalMachine()
     scheduler = scheduler or SequentialScheduler()
     policy = policy or ExecutionPolicy()
     results: dict[str, Result] = {}

{marsh_lib-0.3.2 → marsh_lib-0.3.4}/src/marsh/core/serialization.py

@@ -1,39 +1,17 @@
 """Workflow validation and deterministic serialization."""
 
 import json
-from heapq import heappop, heappush
 from typing import Any, Mapping
 
 from marsh.core.configuration import normalize_workflow
 from marsh.core.domain import Workflow
+from marsh.core.runtime import plan_workflow
 
 
 def validate_workflow(workflow: Workflow | Mapping[str, Any]) -> tuple[str, ...]:
-    workflow = normalize_workflow(workflow)
-    tasks = {task.id: task for task in workflow.tasks}
-    indegree = {task_id: 0 for task_id in tasks}
-    dependents = {task_id: [] for task_id in tasks}
-    for task in workflow.tasks:
-        for dependency in task.dependencies:
-            if dependency not in tasks:
-                raise ValueError(f"task {task.id!r} has unknown dependencies: {dependency}")
-            indegree[task.id] += 1
-            dependents[dependency].append(task.id)
-    ready = []
-    for task_id, degree in indegree.items():
-        if degree == 0:
-            heappush(ready, task_id)
-    order = []
-    while ready:
-        task_id = heappop(ready)
-        order.append(task_id)
-        for dependent in sorted(dependents[task_id]):
-            indegree[dependent] -= 1
-            if indegree[dependent] == 0:
-                heappush(ready, dependent)
-    if len(order) != len(tasks):
-        raise ValueError("workflow contains a dependency cycle")
-    return tuple(order)
+    """Validate dependencies using the canonical planning semantic owner."""
+
+    return plan_workflow(normalize_workflow(workflow)).order
 
 
 def _data(value: Any) -> Any:

{marsh_lib-0.3.2 → marsh_lib-0.3.4}/src/marsh/docker/docker_executor.py

@@ -103,7 +103,11 @@ class DockerContainer:
             self._timer.cancel()
 
         # Remove the Container
-        all_containers: list[Container] = self._client.containers.list(all=True)
+        try:
+            all_containers: list[Container] = self._client.containers.list(all=True)
+        except NotFound:
+            all_containers = []
+
         for container in all_containers:
             if container.name == self._name:
                 try:

marsh_lib-0.3.4/src/marsh/providers/docker_provider.py

@@ -0,0 +1,253 @@
+"""Docker-backed provider adapter for the canonical process contract."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from marsh.core.domain import Machine, Process, ProcessSpec, ProcessStatus, Result, can_transition
+from marsh.core.providers import (
+    ProviderCapabilities,
+    ProviderConfigurationError,
+    ProviderError,
+    ProviderUnavailableError,
+)
+
+
+@dataclass(frozen=True)
+class DockerProviderConfig:
+    """Configuration for Docker process materialization."""
+
+    image: str
+    client_kwargs: dict[str, object]
+
+    def __init__(self, image: str, client_kwargs: dict[str, object] | None = None):
+        image = image.strip()
+        if not image:
+            raise ProviderConfigurationError("docker image must be non-empty")
+        object.__setattr__(self, "image", image)
+        object.__setattr__(self, "client_kwargs", dict(client_kwargs or {}))
+
+
+class DockerProcess:
+    """Process contract backed by one Docker container."""
+
+    def __init__(self, spec: ProcessSpec, config: DockerProviderConfig):
+        self.spec = spec
+        self.config = config
+        self._status = ProcessStatus.CREATED
+        self._result: Result | None = None
+        self._container = None
+        self._client = None
+
+    @property
+    def status(self) -> ProcessStatus:
+        return self._status
+
+    def _transition(self, target: ProcessStatus) -> None:
+        if target is self._status:
+            return
+        if not can_transition(self._status, target):
+            raise RuntimeError(
+                f"invalid process transition: {self._status.value} -> {target.value}"
+            )
+        self._status = target
+
+    def start(self) -> None:
+        if self._status is not ProcessStatus.CREATED:
+            raise RuntimeError(f"cannot start process in {self._status.value} state")
+        if self.spec.stdin is not None:
+            raise ProviderConfigurationError(
+                "DockerProcess does not support ProcessSpec.stdin yet"
+            )
+        self._transition(ProcessStatus.STARTING)
+        try:
+            import docker
+            from docker.errors import DockerException
+        except ImportError as exc:
+            self._transition(ProcessStatus.FAILED)
+            raise ProviderUnavailableError(
+                "Docker provider requires the 'docker' package"
+            ) from exc
+
+        try:
+            self._client = docker.DockerClient(**self.config.client_kwargs)
+            self._container = self._client.containers.create(
+                self.config.image,
+                command=[self.spec.executable, *self.spec.arguments],
+                working_dir=self.spec.working_directory,
+                environment=dict(self.spec.environment),
+                detach=True,
+                auto_remove=False,
+            )
+            self._container.start()
+            self._transition(ProcessStatus.RUNNING)
+        except DockerException as exc:
+            self._transition(ProcessStatus.FAILED)
+            self._result = Result(status=ProcessStatus.FAILED, error=str(exc))
+            self._cleanup()
+            raise ProviderUnavailableError(str(exc)) from exc
+        except Exception as exc:
+            self._transition(ProcessStatus.FAILED)
+            self._result = Result(status=ProcessStatus.FAILED, error=str(exc))
+            self._cleanup()
+            raise ProviderError(str(exc)) from exc
+
+    def wait(self) -> Result:
+        if self._result is not None:
+            return self._result
+        if self._container is None:
+            return Result(status=self._status, error="process was not started")
+        try:
+            status_code = self._container.wait(timeout=self.spec.timeout)["StatusCode"]
+            stdout = self._container.logs(stdout=True, stderr=False)
+            stderr = self._container.logs(stdout=False, stderr=True)
+            status = (
+                ProcessStatus.COMPLETED
+                if status_code == 0
+                else ProcessStatus.FAILED
+            )
+            error = (
+                None
+                if status is ProcessStatus.COMPLETED
+                else f"process exited with code {status_code}"
+            )
+            self._transition(status)
+            self._result = Result(
+                stdout=stdout,
+                stderr=stderr,
+                exit_code=status_code,
+                status=status,
+                error=error,
+            )
+            return self._result
+        except TimeoutError:
+            self._transition(ProcessStatus.TIMED_OUT)
+            self._result = Result(
+                status=ProcessStatus.TIMED_OUT,
+                error="process timed out",
+            )
+            return self._result
+        except Exception as exc:
+            if exc.__class__.__name__ == "ReadTimeout":
+                self._transition(ProcessStatus.TIMED_OUT)
+                self._result = Result(
+                    status=ProcessStatus.TIMED_OUT,
+                    error="process timed out",
+                )
+                return self._result
+            if self._status is ProcessStatus.RUNNING:
+                self._transition(ProcessStatus.FAILED)
+            self._result = Result(status=ProcessStatus.FAILED, error=str(exc))
+            raise ProviderError(str(exc)) from exc
+        finally:
+            self._cleanup()
+
+    def poll(self) -> ProcessStatus:
+        if self._container is None:
+            return self._status
+        self._container.reload()
+        if self._container.status == "exited" and self._status is ProcessStatus.RUNNING:
+            self._transition(
+                ProcessStatus.COMPLETED
+                if self._container.attrs["State"]["ExitCode"] == 0
+                else ProcessStatus.FAILED
+            )
+        return self._status
+
+    def stop(self) -> None:
+        if self._container is not None and self._status is ProcessStatus.RUNNING:
+            try:
+                self._transition(ProcessStatus.STOPPING)
+                self._container.stop(timeout=0)
+                self._transition(ProcessStatus.CANCELLED)
+                self._result = Result(status=ProcessStatus.CANCELLED)
+                self._cleanup()
+            except Exception as exc:
+                if self._status is ProcessStatus.STOPPING:
+                    self._status = ProcessStatus.RUNNING
+                raise ProviderError(str(exc)) from exc
+
+    def terminate(self) -> None:
+        self.stop()
+
+    def kill(self) -> None:
+        if self._container is not None and self._status is ProcessStatus.RUNNING:
+            try:
+                self._transition(ProcessStatus.STOPPING)
+                self._container.kill()
+                self._transition(ProcessStatus.CANCELLED)
+                self._result = Result(status=ProcessStatus.CANCELLED)
+                self._cleanup()
+            except Exception as exc:
+                if self._status is ProcessStatus.STOPPING:
+                    self._status = ProcessStatus.RUNNING
+                raise ProviderError(str(exc)) from exc
+
+    def cancel(self) -> None:
+        if self._status is ProcessStatus.CREATED:
+            self._transition(ProcessStatus.CANCELLED)
+            self._result = Result(status=ProcessStatus.CANCELLED)
+            return
+        self.stop()
+
+    def result(self) -> Result:
+        return self.wait()
+
+    def _cleanup(self) -> None:
+        if self._container is not None:
+            try:
+                self._container.remove(force=True)
+            except Exception:
+                pass
+            self._container = None
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+
+class DockerMachine:
+    """Machine that materializes Docker-backed processes."""
+
+    def __init__(self, config: DockerProviderConfig):
+        self.config = config
+
+    def create_process(self, spec: ProcessSpec) -> DockerProcess:
+        return DockerProcess(spec, self.config)
+
+
+class DockerProvider:
+    """Reference non-local provider; no Workflow semantics live here."""
+
+    name = "docker"
+
+    def __init__(self, image: str = "python:3.12-slim", client_kwargs=None):
+        self.config = DockerProviderConfig(image, client_kwargs)
+
+    @property
+    def capabilities(self) -> ProviderCapabilities:
+        return ProviderCapabilities(
+            {
+                "machine.create",
+                "process.start",
+                "process.wait",
+                "process.poll",
+                "process.stop",
+                "process.terminate",
+                "process.kill",
+                "process.cancel",
+                "process.result",
+            }
+        )
+
+    def create_machine(self, **kwargs) -> Machine:
+        allowed = {"image", "client_kwargs"}
+        unsupported = sorted(set(kwargs) - allowed)
+        if unsupported:
+            raise ProviderConfigurationError(
+                f"unsupported docker provider options: {unsupported}"
+            )
+        config = DockerProviderConfig(
+            kwargs.get("image", self.config.image),
+            kwargs.get("client_kwargs", self.config.client_kwargs),
+        )
+        return DockerMachine(config)

{marsh_lib-0.3.2 → marsh_lib-0.3.4}/uv.lock

@@ -421,12 +421,9 @@ wheels = [
 
 [[package]]
 name = "marsh-lib"
-version = "0.2.0"
+version = "0.3.4"
 source = { editable = "." }
-dependencies = [
-    { name = "docker" },
-    { name = "fabric" },
-]
+dependencies = []
 
 [package.dev-dependencies]
 dev = [
@@ -436,6 +433,8 @@ dev = [
     { name = "pyproject-flake8" },
 ]
 test = [
+    { name = "docker" },
+    { name = "fabric", extra = ["pytest"] },
     { name = "pytest" },
     { name = "pytest-mock" },
     { name = "testcontainers" },
@@ -443,8 +442,8 @@ test = [
 
 [package.metadata]
 requires-dist = [
-    { name = "docker", specifier = ">=7.1.0,<8.0.0" },
-    { name = "fabric", specifier = ">=3.2.2,<4.0.0" },
+    { name = "docker", marker = "extra == 'docker'", specifier = ">=7.1.0,<8.0.0" },
+    { name = "fabric", marker = "extra == 'ssh'", specifier = ">=3.2.2,<4.0.0" },
 ]
 
 [package.metadata.requires-dev]
@@ -455,6 +454,8 @@ dev = [
     { name = "pyproject-flake8", specifier = ">=7.0.0,<8.0.0" },
 ]
 test = [
+    { name = "docker", specifier = ">=7.1.0,<8.0.0" },
+    { name = "fabric", extras = ["pytest"], specifier = ">=3.2.2,<4.0.0" },
     { name = "pytest", specifier = ">=8.3.2,<9.0.0" },
     { name = "pytest-mock", specifier = ">=3.14.0,<4.0.0" },
     { name = "testcontainers", specifier = ">=4.9.0,<5.0.0" },

marsh_lib-0.3.2/docs/architecture.md

@@ -1,35 +0,0 @@
-# Marsh Architecture
-
-## Architecture
-
-Marsh is moving toward a small execution kernel with explicit boundaries:
-
-```mermaid
-flowchart TD
-    A[UX / Python API] --> B[Workflow / Task]
-    B --> C[Validation]
-    C --> D[Planning]
-    D --> E[Scheduler]
-    E --> F[Machine / Process]
-    F --> G[Result]
-```
-
-The architectural goal is to keep:
-
-- workflow intent;
-- execution mechanisms;
-- machines;
-- processes;
-- scheduling;
-- policies;
-- providers;
-- observability; and
-- results
-
-as distinct concepts.
-
-The existing command and DAG APIs remain useful low-level building blocks and compatibility surfaces.
-
-## Implementation status
-
-This document describes the architecture implemented by the current Alpha release. Future capabilities are described only as extension boundaries and are not presented as implemented features.

marsh_lib-0.3.2/src/marsh/__init__.py

@@ -1,2 +0,0 @@
-from marsh.core import *
-from marsh import ssh