flowmesh-sdk-stack 0.1.5__tar.gz → 0.1.6__tar.gz

{flowmesh_sdk_stack-0.1.5/src/flowmesh_sdk_stack.egg-info → flowmesh_sdk_stack-0.1.6}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: flowmesh-sdk-stack
-Version: 0.1.5
+Version: 0.1.6
 Summary: FlowMesh SDK stack client
 License-Expression: Apache-2.0
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: flowmesh-sdk==0.1.5
+Requires-Dist: flowmesh-sdk==0.1.6
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: docker>=7.1.0

{flowmesh_sdk_stack-0.1.5 → flowmesh_sdk_stack-0.1.6}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flowmesh-sdk-stack"
-version = "0.1.5"
+version = "0.1.6"
 description = "FlowMesh SDK stack client"
 readme = "README.md"
 requires-python = ">=3.12"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 dependencies = [
-    "flowmesh-sdk==0.1.5",
+    "flowmesh-sdk==0.1.6",
     "httpx>=0.27.0",
     "pyyaml>=6.0.0",
     "docker>=7.1.0",

{flowmesh_sdk_stack-0.1.5 → flowmesh_sdk_stack-0.1.6/src/flowmesh_sdk_stack.egg-info}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: flowmesh-sdk-stack
-Version: 0.1.5
+Version: 0.1.6
 Summary: FlowMesh SDK stack client
 License-Expression: Apache-2.0
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: flowmesh-sdk==0.1.5
+Requires-Dist: flowmesh-sdk==0.1.6
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: docker>=7.1.0

{flowmesh_sdk_stack-0.1.5 → flowmesh_sdk_stack-0.1.6}/src/flowmesh_sdk_stack.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ src/flowmesh_stack/docker.py
 src/flowmesh_stack/doctor.py
 src/flowmesh_stack/env.py
 src/flowmesh_stack/env_schema.py
+src/flowmesh_stack/image_prune.py
 src/flowmesh_stack/images.py
 src/flowmesh_stack/node_client.py
 src/flowmesh_stack/paths.py

{flowmesh_sdk_stack-0.1.5 → flowmesh_sdk_stack-0.1.6}/src/flowmesh_sdk_stack.egg-info/requires.txt

@@ -1,4 +1,4 @@
-flowmesh-sdk==0.1.5
+flowmesh-sdk==0.1.6
 httpx>=0.27.0
 pyyaml>=6.0.0
 docker>=7.1.0

{flowmesh_sdk_stack-0.1.5 → flowmesh_sdk_stack-0.1.6}/src/flowmesh_stack/__init__.py

@@ -1,6 +1,12 @@
 """FlowMesh SDK — Stack management extensions."""
 
-from .images import BUILD_GROUPS, BUILD_TARGETS, get_image_ref
+from .images import (
+    BUILD_GROUPS,
+    BUILD_TARGETS,
+    get_image_ref,
+    managed_repos,
+    parse_image_ref,
+)
 from .node_client import NodeClient
 from .workers import (
     create_workers,
@@ -17,7 +23,9 @@ __all__ = [
     "create_workers",
     "detect_gpu_targets",
     "get_image_ref",
+    "managed_repos",
     "operate_workers",
+    "parse_image_ref",
     "pull_images",
     "select_worker_images",
 ]

flowmesh_sdk_stack-0.1.6/src/flowmesh_stack/docker.py

@@ -0,0 +1,493 @@
+"""Local Docker and compose helpers for FlowMesh tooling."""
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from .images import managed_repos, parse_image_ref
+
+FLOWMESH_IMAGE_SOURCE = "https://github.com/mlsys-io/FlowMesh"
+"""``org.opencontainers.image.source`` label carried by every FlowMesh image."""
+
+
+class DockerError(RuntimeError):
+    """Raised when a docker command fails."""
+
+
+def ensure_docker_available() -> None:
+    """Verify that the docker CLI is available."""
+    if shutil.which("docker") is None:
+        raise DockerError("docker is required but was not found in PATH")
+
+
+def compose(
+    compose_file: Path,
+    env_file: Path | None,
+    args: Iterable[str],
+    env: Mapping[str, str] | None = None,
+    capture_output: bool = False,
+) -> subprocess.CompletedProcess[str]:
+    """Run docker compose with the provided arguments."""
+    ensure_docker_available()
+    cmd = ["docker", "compose"]
+    if env_file:
+        cmd += ["--env-file", str(env_file)]
+    cmd += ["-f", str(compose_file)]
+    cmd += list(args)
+    merged_env = dict(os.environ)
+    if env:
+        merged_env.update(env)
+    return subprocess.run(
+        cmd,
+        check=False,
+        capture_output=capture_output,
+        text=True,
+        env=merged_env,
+    )
+
+
+def compose_logs(
+    compose_file: Path,
+    env_file: Path | None,
+    env: Mapping[str, str] | None = None,
+    service: str | None = None,
+    capture_output: bool = False,
+    profile: str | None = None,
+) -> subprocess.CompletedProcess[str]:
+    """Stream compose logs, optionally for a specific service."""
+    args: list[str] = []
+    if profile:
+        args += ["--profile", profile]
+    args += ["logs", "-f"]
+    if service:
+        args.append(service)
+    return compose(
+        compose_file=compose_file,
+        env_file=env_file,
+        args=args,
+        env=env,
+        capture_output=capture_output,
+    )
+
+
+def container_logs(
+    container: str,
+    env: Mapping[str, str] | None = None,
+    capture_output: bool = False,
+) -> subprocess.CompletedProcess[str]:
+    """Stream logs for a single container via docker logs."""
+    ensure_docker_available()
+    merged_env = dict(os.environ)
+    if env:
+        merged_env.update(env)
+    return subprocess.run(
+        ["docker", "logs", "-f", container],
+        check=False,
+        capture_output=capture_output,
+        text=True,
+        env=merged_env,
+    )
+
+
+def image_env_overrides(image_tag: str | None) -> dict[str, str]:
+    """Build ``FLOWMESH_VERSION`` overrides for compose commands."""
+    env: dict[str, str] = {}
+    if image_tag:
+        env["FLOWMESH_VERSION"] = image_tag
+    return env
+
+
+@dataclass
+class ManagedImage:
+    """A FlowMesh Docker image present on the local daemon."""
+
+    repo: str
+    tag: str | None
+    target: str | None
+    version: str | None
+    image_id: str
+    size_bytes: int
+    created: datetime | None
+    dangling: bool
+    in_use: bool
+
+    @property
+    def removal_ref(self) -> str:
+        """Reference to pass to ``docker rmi`` (tag when tagged, else image id)."""
+        return self.tag if self.tag else self.image_id
+
+
+@dataclass
+class RemovalResult:
+    """Outcome of removing a single image reference."""
+
+    ref: str
+    ok: bool
+    error: str | None = None
+
+
+_TIMESTAMP_FRACTION = re.compile(r"(\.\d{6})\d+")
+
+
+def _parse_docker_timestamp(value: str) -> datetime | None:
+    """Parse a docker timestamp, or return ``None`` when it can't be determined."""
+    text = value.strip().replace("Z", "+00:00")
+    if not text:
+        return None
+    text = _TIMESTAMP_FRACTION.sub(r"\1", text)
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=UTC)
+
+
+def _docker_json_lines(
+    result: subprocess.CompletedProcess[str],
+) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    for line in result.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(obj, dict):
+            rows.append(obj)
+    return rows
+
+
+@dataclass
+class _ImageMetadata:
+    size_bytes: int
+    created: datetime | None
+    source: str
+
+
+def _inspect_image_metadata(image_ids: list[str]) -> dict[str, _ImageMetadata]:
+    if not image_ids:
+        return {}
+    result = subprocess.run(
+        ["docker", "image", "inspect", *image_ids, "--format", "{{json .}}"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    metadata: dict[str, _ImageMetadata] = {}
+    for obj in _docker_json_lines(result):
+        image_id = obj.get("Id", "")
+        if not isinstance(image_id, str) or not image_id:
+            continue
+        size = obj.get("Size", 0)
+        size_bytes = int(size) if isinstance(size, (int, float)) else 0
+        config = obj.get("Config")
+        labels = config.get("Labels") if isinstance(config, dict) else None
+        source = (
+            str(labels.get("org.opencontainers.image.source") or "")
+            if isinstance(labels, dict)
+            else ""
+        )
+        metadata[image_id] = _ImageMetadata(
+            size_bytes=size_bytes,
+            created=_parse_docker_timestamp(str(obj.get("Created", ""))),
+            source=source,
+        )
+    return metadata
+
+
+def container_image_refs() -> set[str]:
+    """Return the image ids referenced by every container, running or stopped.
+
+    Raises :class:`DockerError` if the daemon can't be queried.
+    """
+    ensure_docker_available()
+    listing = subprocess.run(
+        ["docker", "ps", "-aq"], capture_output=True, text=True, check=False
+    )
+    if listing.returncode != 0:
+        raise DockerError(f"failed to list containers: {listing.stderr.strip()}")
+    container_ids = [
+        stripped for line in listing.stdout.splitlines() if (stripped := line.strip())
+    ]
+    if not container_ids:
+        return set()
+    inspected = subprocess.run(
+        ["docker", "container", "inspect", *container_ids, "--format", "{{.Image}}"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if inspected.returncode != 0:
+        raise DockerError(f"failed to inspect containers: {inspected.stderr.strip()}")
+    return {
+        stripped for line in inspected.stdout.splitlines() if (stripped := line.strip())
+    }
+
+
+def list_managed_images(
+    registry: str,
+    *,
+    include_dangling: bool = False,
+    in_use_ids: set[str] | None = None,
+) -> list[ManagedImage]:
+    """List FlowMesh images on the local daemon.
+
+    Tagged images under a managed repository are attributed to their build target and
+    version. When ``include_dangling`` is set, untagged FlowMesh layers (identified by
+    the ``org.opencontainers.image.source`` label) are included with
+    ``target``/``version`` unset. ``in_use_ids`` marks images referenced by a container.
+    """
+    ensure_docker_available()
+    in_use = in_use_ids or set()
+    repos = managed_repos(registry)
+
+    images: list[ManagedImage] = []
+    listing = subprocess.run(
+        ["docker", "image", "ls", "--no-trunc", "--format", "{{json .}}"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    for row in _docker_json_lines(listing):
+        repo = str(row.get("Repository", ""))
+        tag = str(row.get("Tag", ""))
+        image_id = str(row.get("ID", ""))
+        if repo not in repos or not image_id or tag == "<none>":
+            continue
+        ref = f"{repo}:{tag}"
+        parsed = parse_image_ref(registry, ref)
+        target, version = parsed if parsed else (None, None)
+        images.append(
+            ManagedImage(
+                repo=repo,
+                tag=ref,
+                target=target,
+                version=version,
+                image_id=image_id,
+                size_bytes=0,
+                created=None,
+                dangling=False,
+                in_use=image_id in in_use,
+            )
+        )
+
+    if include_dangling:
+        dangling = subprocess.run(
+            [
+                "docker",
+                "image",
+                "ls",
+                "--no-trunc",
+                "--filter",
+                "dangling=true",
+                "--filter",
+                f"label=org.opencontainers.image.source={FLOWMESH_IMAGE_SOURCE}",
+                "--format",
+                "{{json .}}",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        for row in _docker_json_lines(dangling):
+            image_id = str(row.get("ID", ""))
+            if not image_id:
+                continue
+            images.append(
+                ManagedImage(
+                    repo=str(row.get("Repository", "<none>")),
+                    tag=None,
+                    target=None,
+                    version=None,
+                    image_id=image_id,
+                    size_bytes=0,
+                    created=None,
+                    dangling=True,
+                    in_use=image_id in in_use,
+                )
+            )
+
+    metadata = _inspect_image_metadata([image.image_id for image in images])
+    resolved: list[ManagedImage] = []
+    for image in images:
+        meta = metadata.get(image.image_id)
+        if meta is None or meta.source != FLOWMESH_IMAGE_SOURCE:
+            continue
+        image.size_bytes = meta.size_bytes
+        image.created = meta.created
+        resolved.append(image)
+    return resolved
+
+
+def remove_images(refs: list[str], *, force: bool = False) -> list[RemovalResult]:
+    """Remove image references via ``docker rmi``, reporting each outcome.
+
+    Never aborts mid-batch: a failed removal is recorded and the rest proceed.
+    """
+    ensure_docker_available()
+    results: list[RemovalResult] = []
+    for ref in refs:
+        args = ["docker", "rmi"]
+        if force:
+            args.append("-f")
+        args.append(ref)
+        result = subprocess.run(args, capture_output=True, text=True, check=False)
+        if result.returncode == 0:
+            results.append(RemovalResult(ref=ref, ok=True))
+        else:
+            error = (result.stderr or result.stdout).strip()
+            results.append(RemovalResult(ref=ref, ok=False, error=error or None))
+    return results
+
+
+@dataclass
+class ServerWorkerStatusRow:
+    name: str
+    status: str
+    worker_type: str
+    gpu_id: str
+
+
+def server_worker_status_rows(
+    *, include_exited: bool = False
+) -> list[ServerWorkerStatusRow]:
+    """Return status rows for local server worker containers."""
+
+    def _inspect(name: str, fmt: str) -> str:
+        result = subprocess.run(
+            ["docker", "inspect", "--format", fmt, name],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            return ""
+        return result.stdout.strip()
+
+    ensure_docker_available()
+    cmd = [
+        "docker",
+        "ps",
+        "-a" if include_exited else "",
+        "--filter",
+        "label=flowmesh.group=server-workers",
+        "--format",
+        "{{.Names}}\t{{.Status}}",
+    ]
+    cmd = [part for part in cmd if part]
+    result = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    rows = result.stdout.strip()
+    if not rows:
+        return []
+
+    items: list[ServerWorkerStatusRow] = []
+    for line in rows.splitlines():
+        if not line.strip():
+            continue
+        name, status = (line.split("\t", 1) + [""])[:2]
+        worker_type = _inspect(name, '{{index .Config.Labels "flowmesh.worker.type"}}')
+        gpu_id = _inspect(name, '{{index .Config.Labels "flowmesh.worker.gpu_id"}}')
+        if not worker_type:
+            env_dump = _inspect(name, "{{range .Config.Env}}{{println .}}{{end}}")
+            detected_gpu = ""
+            for entry in env_dump.splitlines():
+                if entry.startswith("WORKER_HOST_GPU_ID="):
+                    detected_gpu = entry.split("=", 1)[1]
+                    break
+            if detected_gpu:
+                worker_type = "gpu"
+                gpu_id = detected_gpu
+            else:
+                worker_type = "cpu"
+        items.append(
+            ServerWorkerStatusRow(
+                name=name,
+                status=status,
+                worker_type=worker_type or "unknown",
+                gpu_id=gpu_id or "-",
+            )
+        )
+    return items
+
+
+@dataclass
+class DockerComposeStack:
+    """Local compose wrapper."""
+
+    compose_file: Path
+    """Path to the compose file used for all stack operations."""
+    env_file_var: str
+    """
+    Environment variable name passed to compose to point at the selected env file.
+    """
+    load_env: Callable[[Path], None]
+    """
+    Callback that loads and resolves env-file values before stack operations run.
+    """
+    ensure_deploy_paths: Callable[[Path], None] | None = None
+    """
+    Optional callback that prepares required local files and directories before 
+    deployment-oriented compose commands.
+    """
+
+    def run(
+        self,
+        args: list[str],
+        env_file: Path,
+        env: dict[str, str] | None = None,
+        to_deploy: bool = False,
+    ) -> subprocess.CompletedProcess[str]:
+        """Run ``docker compose`` for this stack."""
+        self.load_env(env_file)
+        if to_deploy and self.ensure_deploy_paths is not None:
+            self.ensure_deploy_paths(Path.cwd())
+        compose_env = {self.env_file_var: str(env_file.resolve())}
+        if env:
+            compose_env.update(env)
+        return compose(
+            compose_file=self.compose_file,
+            env_file=env_file,
+            args=args,
+            env=compose_env,
+        )
+
+    def stream_logs(
+        self,
+        env_file: Path,
+        service: str | None = None,
+        profile: str | None = None,
+    ) -> int:
+        """Stream stack logs and fall back to container logs when needed."""
+        self.load_env(env_file)
+        compose_env = {self.env_file_var: str(env_file.resolve())}
+        if service:
+            result = compose_logs(
+                compose_file=self.compose_file,
+                env_file=env_file,
+                env=compose_env,
+                service=service,
+                capture_output=False,
+                profile=profile,
+            )
+            if result.returncode == 0:
+                return 0
+            fallback = container_logs(container=service, env=None, capture_output=False)
+            return fallback.returncode
+
+        result = compose_logs(
+            compose_file=self.compose_file,
+            env_file=env_file,
+            env=compose_env,
+            capture_output=False,
+            profile=profile,
+        )
+        return result.returncode

flowmesh_sdk_stack-0.1.6/src/flowmesh_stack/image_prune.py

@@ -0,0 +1,128 @@
+"""Policy-based selection for ``flowmesh stack image prune``.
+
+Pure logic over :class:`~flowmesh_stack.docker.ManagedImage` lists: the caller
+supplies the discovered images (with ``in_use`` already populated) and the
+policy flags; :func:`select_prune_targets` returns which images to delete and
+which are protected. Docker is never touched here.
+"""
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+
+from .docker import ManagedImage
+
+_DURATION = re.compile(r"^(\d+)([smhdw])$")
+_UNIT_SECONDS = {"s": 1, "m": 60, "h": 3600, "d": 86400, "w": 604800}
+
+
+def parse_duration(text: str) -> timedelta:
+    """Parse a ``<int><unit>`` duration (units ``s``/``m``/``h``/``d``/``w``)."""
+    match = _DURATION.match(text.strip())
+    if not match:
+        raise ValueError(
+            f"invalid duration {text!r}; expected an integer followed by one of "
+            "s, m, h, d, w (e.g. 30d, 12h)"
+        )
+    return timedelta(seconds=int(match.group(1)) * _UNIT_SECONDS[match.group(2)])
+
+
+@dataclass
+class PrunePlan:
+    """Result of a prune selection: what to delete and what is protected."""
+
+    deleted: list[ManagedImage] = field(default_factory=list)
+    protected: list[tuple[ManagedImage, str]] = field(default_factory=list)
+
+
+def _keep_last_versions(
+    parsed: list[ManagedImage], keep_last: int
+) -> dict[str, set[str]]:
+    newest: dict[str, dict[str, datetime]] = {}
+    ignored: list[tuple[str, str]] = []
+    for image in parsed:
+        if image.target is None or image.version is None:
+            continue
+        if image.created is None:
+            ignored.append((image.target, image.version))
+            continue
+        per_target = newest.setdefault(image.target, {})
+        if image.version not in per_target or image.created > per_target[image.version]:
+            per_target[image.version] = image.created
+    protected: dict[str, set[str]] = {}
+    for target, versions in newest.items():
+        ordered = sorted(versions.items(), key=lambda item: item[1], reverse=True)
+        protected[target] = {version for version, _ in ordered[:keep_last]}
+    for target, version in ignored:
+        protected.setdefault(target, set()).add(version)
+    return protected
+
+
+def select_prune_targets(
+    images: list[ManagedImage],
+    *,
+    keep_last: int | None = None,
+    keep_versions: set[str] | None = None,
+    keep_active: bool = False,
+    older_than: timedelta | None = None,
+    include_dangling: bool = False,
+    now: datetime,
+) -> PrunePlan:
+    """Select images to prune as ``candidate pool − protected``.
+
+    The candidate pool is a filter — protections only subtract from it. The
+    non-dangling base is restricted to parsed images (``target`` set) so manual
+    tags on a managed repo are never candidates. Images whose ``created`` time
+    couldn't be determined (``None``) are never selected by ``older_than``.
+    """
+    if keep_last is not None and keep_last < 0:
+        raise ValueError("keep_last must be >= 0")
+    keep_versions = keep_versions or set()
+    parsed = [i for i in images if not i.dangling and i.target is not None]
+    dangling = [i for i in images if i.dangling]
+
+    if older_than is not None:
+        cutoff = now - older_than
+        pool: list[ManagedImage] = [
+            i for i in parsed if i.created is not None and i.created < cutoff
+        ]
+    elif keep_last is not None:
+        pool = list(parsed)
+    else:
+        pool = []
+    if include_dangling:
+        pool = pool + dangling
+
+    keep_last_versions = (
+        _keep_last_versions(parsed, keep_last) if keep_last is not None else {}
+    )
+
+    plan = PrunePlan()
+    for image in pool:
+        reason = _protection_reason(
+            image, keep_last_versions, keep_versions, keep_active
+        )
+        if reason is None:
+            plan.deleted.append(image)
+        else:
+            plan.protected.append((image, reason))
+    return plan
+
+
+def _protection_reason(
+    image: ManagedImage,
+    keep_last_versions: dict[str, set[str]],
+    keep_versions: set[str],
+    keep_active: bool,
+) -> str | None:
+    if keep_active and image.in_use:
+        return "keep-active"
+    if image.version is not None and image.version in keep_versions:
+        return "keep"
+    if (
+        image.target is not None
+        and image.version is not None
+        and image.version in keep_last_versions.get(image.target, set())
+    ):
+        return "keep-last"
+    return None

{flowmesh_sdk_stack-0.1.5 → flowmesh_sdk_stack-0.1.6}/src/flowmesh_stack/images.py

@@ -4,23 +4,23 @@ Provides the canonical mapping from build targets to image references,
 used by both the CLI dev commands and programmatic build/deploy scripts.
 """
 
+_TARGET_COMPONENTS: dict[str, tuple[str, str]] = {
+    "flowmesh_server": ("flowmesh_server", ""),
+    "flowmesh_worker_cpu": ("flowmesh_worker", "-cpu"),
+    "flowmesh_worker_gpu_builder": ("flowmesh_worker_builder", "-gpu"),
+    "flowmesh_worker_gpu": ("flowmesh_worker", "-gpu"),
+    "flowmesh_ssh_cpu": ("flowmesh_ssh", "-cpu"),
+    "flowmesh_ssh_gpu": ("flowmesh_ssh", "-gpu"),
+}
 BUILD_TARGETS: dict[str, str] = {
-    "flowmesh_server": "{registry}/flowmesh_server:{version}",
-    "flowmesh_worker_cpu": "{registry}/flowmesh_worker:{version}-cpu",
-    "flowmesh_worker_gpu_builder": "{registry}/flowmesh_worker_builder:{version}-gpu",
-    "flowmesh_worker_gpu": "{registry}/flowmesh_worker:{version}-gpu",
-    "flowmesh_ssh_cpu": "{registry}/flowmesh_ssh:{version}-cpu",
-    "flowmesh_ssh_gpu": "{registry}/flowmesh_ssh:{version}-gpu",
+    target: f"{{registry}}/{repo}:{{version}}{suffix}"
+    for target, (repo, suffix) in _TARGET_COMPONENTS.items()
 }
 """Mapping from build target name to image reference format string."""
 
 CACHE_TARGETS: dict[str, str] = {
-    "flowmesh_server": "{registry}/flowmesh_server:{scope}",
-    "flowmesh_worker_cpu": "{registry}/flowmesh_worker:{scope}-cpu",
-    "flowmesh_worker_gpu_builder": "{registry}/flowmesh_worker_builder:{scope}-gpu",
-    "flowmesh_worker_gpu": "{registry}/flowmesh_worker:{scope}-gpu",
-    "flowmesh_ssh_cpu": "{registry}/flowmesh_ssh:{scope}-cpu",
-    "flowmesh_ssh_gpu": "{registry}/flowmesh_ssh:{scope}-gpu",
+    target: f"{{registry}}/{repo}:{{scope}}{suffix}"
+    for target, (repo, suffix) in _TARGET_COMPONENTS.items()
 }
 """Mapping from build target name to registry cache reference format string."""
 
@@ -110,3 +110,51 @@ def get_push_platforms(target: str) -> str:
     if target not in PUSH_PLATFORMS:
         raise ValueError(f"Unknown build target: {target}")
     return PUSH_PLATFORMS[target]
+
+
+_RESERVED_CACHE_VERSION = "cache"
+_RESERVED_CACHE_PREFIX = "cache-"
+
+
+def _split_repo_tag(ref: str) -> tuple[str, str] | None:
+    """Split an image ref into ``(repo, tag)``, or ``None`` when it has no tag.
+
+    Splits on the final colon and applies the Docker rule that a colon whose right side
+    contains ``/`` is a registry port, not a tag separator (e.g.
+    ``localhost:5000/org/img``).
+    """
+    repo, sep, tag = ref.rpartition(":")
+    return (repo, tag) if sep and "/" not in tag else None
+
+
+def managed_repos(registry: str) -> set[str]:
+    """Return the distinct image repositories FlowMesh publishes under a registry."""
+    return {f"{registry}/{_TARGET_COMPONENTS[target][0]}" for target in BUILD_TARGETS}
+
+
+def parse_image_ref(registry: str, ref: str) -> tuple[str, str] | None:
+    """Map a concrete image reference back to its ``(target, version)``.
+
+    Inverse of :func:`get_image_ref`. Returns ``None`` for references outside the
+    managed repositories, references without a tag, and cache-scope tags reserved by
+    :data:`CACHE_TARGETS` (``cache`` / ``cache-*``), which are registry-only and must
+    never be treated as prunable versions.
+    """
+    split = _split_repo_tag(ref)
+    if split is None:
+        return None
+    repo, tag = split
+    for target, (target_repo, suffix) in _TARGET_COMPONENTS.items():
+        if repo != f"{registry}/{target_repo}":
+            continue
+        if suffix and not tag.endswith(suffix):
+            continue
+        version = tag.removesuffix(suffix)
+        if not version:
+            continue
+        if version == _RESERVED_CACHE_VERSION or version.startswith(
+            _RESERVED_CACHE_PREFIX
+        ):
+            return None
+        return target, version
+    return None

flowmesh_sdk_stack-0.1.5/src/flowmesh_stack/docker.py

@@ -1,262 +0,0 @@
-"""Local Docker and compose helpers for FlowMesh tooling."""
-
-import os
-import shutil
-import subprocess
-from collections.abc import Callable, Iterable, Mapping
-from dataclasses import dataclass
-from pathlib import Path
-
-
-class DockerError(RuntimeError):
-    """Raised when a docker command fails."""
-
-
-def ensure_docker_available() -> None:
-    """Verify that the docker CLI is available."""
-    if shutil.which("docker") is None:
-        raise DockerError("docker is required but was not found in PATH")
-
-
-def compose(
-    compose_file: Path,
-    env_file: Path | None,
-    args: Iterable[str],
-    env: Mapping[str, str] | None = None,
-    capture_output: bool = False,
-) -> subprocess.CompletedProcess[str]:
-    """Run docker compose with the provided arguments."""
-    ensure_docker_available()
-    cmd = ["docker", "compose"]
-    if env_file:
-        cmd += ["--env-file", str(env_file)]
-    cmd += ["-f", str(compose_file)]
-    cmd += list(args)
-    merged_env = dict(os.environ)
-    if env:
-        merged_env.update(env)
-    return subprocess.run(
-        cmd,
-        check=False,
-        capture_output=capture_output,
-        text=True,
-        env=merged_env,
-    )
-
-
-def compose_logs(
-    compose_file: Path,
-    env_file: Path | None,
-    env: Mapping[str, str] | None = None,
-    service: str | None = None,
-    capture_output: bool = False,
-    profile: str | None = None,
-) -> subprocess.CompletedProcess[str]:
-    """Stream compose logs, optionally for a specific service."""
-    args: list[str] = []
-    if profile:
-        args += ["--profile", profile]
-    args += ["logs", "-f"]
-    if service:
-        args.append(service)
-    return compose(
-        compose_file=compose_file,
-        env_file=env_file,
-        args=args,
-        env=env,
-        capture_output=capture_output,
-    )
-
-
-def container_logs(
-    container: str,
-    env: Mapping[str, str] | None = None,
-    capture_output: bool = False,
-) -> subprocess.CompletedProcess[str]:
-    """Stream logs for a single container via docker logs."""
-    ensure_docker_available()
-    merged_env = dict(os.environ)
-    if env:
-        merged_env.update(env)
-    return subprocess.run(
-        ["docker", "logs", "-f", container],
-        check=False,
-        capture_output=capture_output,
-        text=True,
-        env=merged_env,
-    )
-
-
-def inspect_image(
-    image: str, capture_output: bool = False
-) -> subprocess.CompletedProcess[str]:
-    """Inspect a docker image by tag."""
-    ensure_docker_available()
-    return subprocess.run(
-        ["docker", "image", "inspect", image],
-        check=False,
-        capture_output=capture_output,
-        text=True,
-    )
-
-
-def remove_image(
-    image: str, capture_output: bool = False
-) -> subprocess.CompletedProcess[str]:
-    """Remove a docker image by tag."""
-    ensure_docker_available()
-    return subprocess.run(
-        ["docker", "rmi", image], check=False, capture_output=capture_output, text=True
-    )
-
-
-def image_env_overrides(image_tag: str | None) -> dict[str, str]:
-    """Build ``FLOWMESH_VERSION`` overrides for compose commands."""
-    env: dict[str, str] = {}
-    if image_tag:
-        env["FLOWMESH_VERSION"] = image_tag
-    return env
-
-
-@dataclass
-class ServerWorkerStatusRow:
-    name: str
-    status: str
-    worker_type: str
-    gpu_id: str
-
-
-def server_worker_status_rows(
-    *, include_exited: bool = False
-) -> list[ServerWorkerStatusRow]:
-    """Return status rows for local server worker containers."""
-
-    def _inspect(name: str, fmt: str) -> str:
-        result = subprocess.run(
-            ["docker", "inspect", "--format", fmt, name],
-            capture_output=True,
-            text=True,
-            check=False,
-        )
-        if result.returncode != 0:
-            return ""
-        return result.stdout.strip()
-
-    ensure_docker_available()
-    cmd = [
-        "docker",
-        "ps",
-        "-a" if include_exited else "",
-        "--filter",
-        "label=flowmesh.group=server-workers",
-        "--format",
-        "{{.Names}}\t{{.Status}}",
-    ]
-    cmd = [part for part in cmd if part]
-    result = subprocess.run(cmd, capture_output=True, text=True, check=False)
-    rows = result.stdout.strip()
-    if not rows:
-        return []
-
-    items: list[ServerWorkerStatusRow] = []
-    for line in rows.splitlines():
-        if not line.strip():
-            continue
-        name, status = (line.split("\t", 1) + [""])[:2]
-        worker_type = _inspect(name, '{{index .Config.Labels "flowmesh.worker.type"}}')
-        gpu_id = _inspect(name, '{{index .Config.Labels "flowmesh.worker.gpu_id"}}')
-        if not worker_type:
-            env_dump = _inspect(name, "{{range .Config.Env}}{{println .}}{{end}}")
-            detected_gpu = ""
-            for entry in env_dump.splitlines():
-                if entry.startswith("WORKER_HOST_GPU_ID="):
-                    detected_gpu = entry.split("=", 1)[1]
-                    break
-            if detected_gpu:
-                worker_type = "gpu"
-                gpu_id = detected_gpu
-            else:
-                worker_type = "cpu"
-        items.append(
-            ServerWorkerStatusRow(
-                name=name,
-                status=status,
-                worker_type=worker_type or "unknown",
-                gpu_id=gpu_id or "-",
-            )
-        )
-    return items
-
-
-@dataclass
-class DockerComposeStack:
-    """Local compose wrapper."""
-
-    compose_file: Path
-    """Path to the compose file used for all stack operations."""
-    env_file_var: str
-    """
-    Environment variable name passed to compose to point at the selected env file.
-    """
-    load_env: Callable[[Path], None]
-    """
-    Callback that loads and resolves env-file values before stack operations run.
-    """
-    ensure_deploy_paths: Callable[[Path], None] | None = None
-    """
-    Optional callback that prepares required local files and directories before 
-    deployment-oriented compose commands.
-    """
-
-    def run(
-        self,
-        args: list[str],
-        env_file: Path,
-        env: dict[str, str] | None = None,
-        to_deploy: bool = False,
-    ) -> subprocess.CompletedProcess[str]:
-        """Run ``docker compose`` for this stack."""
-        self.load_env(env_file)
-        if to_deploy and self.ensure_deploy_paths is not None:
-            self.ensure_deploy_paths(Path.cwd())
-        compose_env = {self.env_file_var: str(env_file.resolve())}
-        if env:
-            compose_env.update(env)
-        return compose(
-            compose_file=self.compose_file,
-            env_file=env_file,
-            args=args,
-            env=compose_env,
-        )
-
-    def stream_logs(
-        self,
-        env_file: Path,
-        service: str | None = None,
-        profile: str | None = None,
-    ) -> int:
-        """Stream stack logs and fall back to container logs when needed."""
-        self.load_env(env_file)
-        compose_env = {self.env_file_var: str(env_file.resolve())}
-        if service:
-            result = compose_logs(
-                compose_file=self.compose_file,
-                env_file=env_file,
-                env=compose_env,
-                service=service,
-                capture_output=False,
-                profile=profile,
-            )
-            if result.returncode == 0:
-                return 0
-            fallback = container_logs(container=service, env=None, capture_output=False)
-            return fallback.returncode
-
-        result = compose_logs(
-            compose_file=self.compose_file,
-            env_file=env_file,
-            env=compose_env,
-            capture_output=False,
-            profile=profile,
-        )
-        return result.returncode