clean-to-execute 0.0.1__tar.gz

clean_to_execute-0.0.1/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: clean-to-execute
+Version: 0.0.1
+Summary: Safely clean the Docker Compose resources for a local GitHub repository.
+Author: Kaizten Analytics
+License-Expression: LicenseRef-Proprietary
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Clean to Execute
+
+`clean-to-execute` removes Docker Compose resources for a local clone of a
+GitHub repository.
+
+The repository is found recursively by inspecting Git remotes under the user's
+home directory. Directory names alone are not trusted. Docker Compose files
+must be at the repository root.
+
+## Requirements
+
+- Python 3.10 or newer
+- Git
+- Docker with the Compose plugin
+- Access to a running Docker daemon
+
+## Installation
+
+From this directory:
+
+```bash
+python3 -m pip install .
+```
+
+## Usage
+
+Execute cleanup:
+
+```bash
+clean-to-execute --organization kaizten --repository example
+```
+
+Preview cleanup without changing Docker resources:
+
+```bash
+clean-to-execute --organization kaizten --repository example --dry-run
+```
+
+Search somewhere other than `~`:
+
+```bash
+clean-to-execute \
+  --organization kaizten \
+  --repository example \
+  --root /workspaces
+```
+
+Cleanup is destructive by default. Use `--dry-run` when only a preview is
+required.
+
+## Cleanup scope
+
+The command recognizes `compose.yaml`, `compose.yml`, `docker-compose.yaml`,
+and `docker-compose.yml` at the repository root. Docker Compose renders the
+effective configuration, including its normal override and environment
+interpolation behavior. All Compose profiles are activated for inspection and
+shutdown, so services and ports behind profiles are included without requiring
+the caller to name each profile.
+
+By default, the command:
+
+1. Stops and removes the entire Compose project, including orphan containers,
+   so all of its published ports are released.
+2. Deletes the project's non-external named and anonymous volumes.
+3. Deletes all other dangling Docker volumes, while preserving external
+   volumes declared by this Compose project.
+4. Force-removes local images referenced by the Compose configuration whose
+   namespace matches the GitHub organization.
+
+The namespace comparison works across registries. For example, all of these
+belong to the GitHub organization `kaizten`:
+
+- `kaizten/api`
+- `docker.io/kaizten/api`
+- `ghcr.io/kaizten/api`
+- `registry.example.com/kaizten/api`
+
+Containers outside the selected Compose project are never stopped or removed.
+An external container may still prevent Docker from deleting an image; that is
+reported as a cleanup failure.
+
+If multiple local clones match the same GitHub remote, the command lists them
+and exits instead of choosing one implicitly.
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -v
+./build-package.sh
+```

clean_to_execute-0.0.1/README.md

@@ -0,0 +1,90 @@
+# Clean to Execute
+
+`clean-to-execute` removes Docker Compose resources for a local clone of a
+GitHub repository.
+
+The repository is found recursively by inspecting Git remotes under the user's
+home directory. Directory names alone are not trusted. Docker Compose files
+must be at the repository root.
+
+## Requirements
+
+- Python 3.10 or newer
+- Git
+- Docker with the Compose plugin
+- Access to a running Docker daemon
+
+## Installation
+
+From this directory:
+
+```bash
+python3 -m pip install .
+```
+
+## Usage
+
+Execute cleanup:
+
+```bash
+clean-to-execute --organization kaizten --repository example
+```
+
+Preview cleanup without changing Docker resources:
+
+```bash
+clean-to-execute --organization kaizten --repository example --dry-run
+```
+
+Search somewhere other than `~`:
+
+```bash
+clean-to-execute \
+  --organization kaizten \
+  --repository example \
+  --root /workspaces
+```
+
+Cleanup is destructive by default. Use `--dry-run` when only a preview is
+required.
+
+## Cleanup scope
+
+The command recognizes `compose.yaml`, `compose.yml`, `docker-compose.yaml`,
+and `docker-compose.yml` at the repository root. Docker Compose renders the
+effective configuration, including its normal override and environment
+interpolation behavior. All Compose profiles are activated for inspection and
+shutdown, so services and ports behind profiles are included without requiring
+the caller to name each profile.
+
+By default, the command:
+
+1. Stops and removes the entire Compose project, including orphan containers,
+   so all of its published ports are released.
+2. Deletes the project's non-external named and anonymous volumes.
+3. Deletes all other dangling Docker volumes, while preserving external
+   volumes declared by this Compose project.
+4. Force-removes local images referenced by the Compose configuration whose
+   namespace matches the GitHub organization.
+
+The namespace comparison works across registries. For example, all of these
+belong to the GitHub organization `kaizten`:
+
+- `kaizten/api`
+- `docker.io/kaizten/api`
+- `ghcr.io/kaizten/api`
+- `registry.example.com/kaizten/api`
+
+Containers outside the selected Compose project are never stopped or removed.
+An external container may still prevent Docker from deleting an image; that is
+reported as a cleanup failure.
+
+If multiple local clones match the same GitHub remote, the command lists them
+and exits instead of choosing one implicitly.
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -v
+./build-package.sh
+```

clean_to_execute-0.0.1/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "clean-to-execute"
+version = "0.0.1"
+description = "Safely clean the Docker Compose resources for a local GitHub repository."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Proprietary"
+authors = [{ name = "Kaizten Analytics" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+[project.scripts]
+clean-to-execute = "clean_to_execute:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+py-modules = ["clean_to_execute"]

clean_to_execute-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

clean_to_execute-0.0.1/src/clean_to_execute.egg-info/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: clean-to-execute
+Version: 0.0.1
+Summary: Safely clean the Docker Compose resources for a local GitHub repository.
+Author: Kaizten Analytics
+License-Expression: LicenseRef-Proprietary
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Clean to Execute
+
+`clean-to-execute` removes Docker Compose resources for a local clone of a
+GitHub repository.
+
+The repository is found recursively by inspecting Git remotes under the user's
+home directory. Directory names alone are not trusted. Docker Compose files
+must be at the repository root.
+
+## Requirements
+
+- Python 3.10 or newer
+- Git
+- Docker with the Compose plugin
+- Access to a running Docker daemon
+
+## Installation
+
+From this directory:
+
+```bash
+python3 -m pip install .
+```
+
+## Usage
+
+Execute cleanup:
+
+```bash
+clean-to-execute --organization kaizten --repository example
+```
+
+Preview cleanup without changing Docker resources:
+
+```bash
+clean-to-execute --organization kaizten --repository example --dry-run
+```
+
+Search somewhere other than `~`:
+
+```bash
+clean-to-execute \
+  --organization kaizten \
+  --repository example \
+  --root /workspaces
+```
+
+Cleanup is destructive by default. Use `--dry-run` when only a preview is
+required.
+
+## Cleanup scope
+
+The command recognizes `compose.yaml`, `compose.yml`, `docker-compose.yaml`,
+and `docker-compose.yml` at the repository root. Docker Compose renders the
+effective configuration, including its normal override and environment
+interpolation behavior. All Compose profiles are activated for inspection and
+shutdown, so services and ports behind profiles are included without requiring
+the caller to name each profile.
+
+By default, the command:
+
+1. Stops and removes the entire Compose project, including orphan containers,
+   so all of its published ports are released.
+2. Deletes the project's non-external named and anonymous volumes.
+3. Deletes all other dangling Docker volumes, while preserving external
+   volumes declared by this Compose project.
+4. Force-removes local images referenced by the Compose configuration whose
+   namespace matches the GitHub organization.
+
+The namespace comparison works across registries. For example, all of these
+belong to the GitHub organization `kaizten`:
+
+- `kaizten/api`
+- `docker.io/kaizten/api`
+- `ghcr.io/kaizten/api`
+- `registry.example.com/kaizten/api`
+
+Containers outside the selected Compose project are never stopped or removed.
+An external container may still prevent Docker from deleting an image; that is
+reported as a cleanup failure.
+
+If multiple local clones match the same GitHub remote, the command lists them
+and exits instead of choosing one implicitly.
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -v
+./build-package.sh
+```

clean_to_execute-0.0.1/src/clean_to_execute.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+src/clean_to_execute.py
+src/clean_to_execute.egg-info/PKG-INFO
+src/clean_to_execute.egg-info/SOURCES.txt
+src/clean_to_execute.egg-info/dependency_links.txt
+src/clean_to_execute.egg-info/entry_points.txt
+src/clean_to_execute.egg-info/top_level.txt
+tests/test_clean_to_execute.py

clean_to_execute-0.0.1/src/clean_to_execute.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

clean_to_execute-0.0.1/src/clean_to_execute.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clean-to-execute = clean_to_execute:main

clean_to_execute-0.0.1/src/clean_to_execute.egg-info/top_level.txt

@@ -0,0 +1 @@
+clean_to_execute

clean_to_execute-0.0.1/src/clean_to_execute.py

@@ -0,0 +1,459 @@
+#!/usr/bin/env python3
+"""Clean Docker Compose resources belonging to a local GitHub repository."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import urllib.parse
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Sequence
+
+
+COMPOSE_FILES = ("compose.yaml", "compose.yml", "docker-compose.yaml", "docker-compose.yml")
+SKIP_DIRS = {
+    ".cache",
+    ".git",
+    ".hg",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "node_modules",
+    "venv",
+}
+
+
+class CleanError(RuntimeError):
+    """A user-facing validation or cleanup error."""
+
+
+@dataclass(frozen=True)
+class CommandResult:
+    args: tuple[str, ...]
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+@dataclass(frozen=True)
+class ContainerInfo:
+    container_id: str
+    name: str
+    image: str
+    ports: tuple[str, ...]
+    volumes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class CleanupPlan:
+    repository: Path
+    project_name: str
+    containers: tuple[ContainerInfo, ...]
+    declared_ports: tuple[str, ...]
+    project_volumes: tuple[str, ...]
+    external_volumes: tuple[str, ...]
+    dangling_volumes: tuple[str, ...]
+    organization_images: tuple[str, ...]
+    local_organization_images: tuple[str, ...]
+
+
+def command(args: Sequence[str], cwd: Path | None = None) -> CommandResult:
+    try:
+        completed = subprocess.run(
+            list(args),
+            cwd=cwd,
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except OSError as exc:
+        raise CleanError(f"Could not run {args[0]}: {exc}") from exc
+    return CommandResult(tuple(args), completed.returncode, completed.stdout.strip(), completed.stderr.strip())
+
+
+def require_success(result: CommandResult, context: str) -> str:
+    if result.returncode == 0:
+        return result.stdout
+    detail = result.stderr or result.stdout or f"exit status {result.returncode}"
+    raise CleanError(f"{context}: {detail}")
+
+
+def github_name(value: str) -> str:
+    if not re.fullmatch(r"[A-Za-z0-9](?:[A-Za-z0-9_.-]*[A-Za-z0-9])?", value):
+        raise argparse.ArgumentTypeError("must be a GitHub organization or repository name")
+    return value
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Clean Docker Compose resources for a local GitHub repository."
+    )
+    parser.add_argument("--organization", required=True, type=github_name, help="GitHub organization name.")
+    parser.add_argument("--repository", required=True, type=github_name, help="GitHub repository name.")
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=Path.home(),
+        help="Directory to search recursively. Defaults to the user home directory.",
+    )
+    parser.add_argument("--dry-run", action="store_true", help="Preview the cleanup without changing Docker resources.")
+    return parser
+
+
+def normalize_github_remote(url: str) -> tuple[str, str] | None:
+    value = url.strip()
+    scp_match = re.match(r"^[^@\s]+@github\.com:([^/]+)/(.+?)(?:\.git)?$", value, re.IGNORECASE)
+    if scp_match:
+        return scp_match.group(1).lower(), re.sub(r"\.git$", "", scp_match.group(2), flags=re.IGNORECASE).lower()
+
+    parsed = urllib.parse.urlparse(value)
+    if parsed.hostname and parsed.hostname.lower() == "github.com":
+        parts = [part for part in parsed.path.strip("/").split("/") if part]
+        if len(parts) == 2:
+            return parts[0].lower(), re.sub(r"\.git$", "", parts[1], flags=re.IGNORECASE).lower()
+    return None
+
+
+def repository_remotes(repository: Path) -> set[tuple[str, str]]:
+    result = command(["git", "-C", str(repository), "remote", "-v"])
+    if result.returncode != 0:
+        return set()
+    remotes: set[tuple[str, str]] = set()
+    for line in result.stdout.splitlines():
+        fields = line.split()
+        if len(fields) < 2:
+            continue
+        normalized = normalize_github_remote(fields[1])
+        if normalized:
+            remotes.add(normalized)
+    return remotes
+
+
+def find_repository(root: Path, organization: str, repository: str) -> Path:
+    search_root = root.expanduser().resolve()
+    if not search_root.exists():
+        raise CleanError(f"Search root does not exist: {search_root}")
+    if not search_root.is_dir():
+        raise CleanError(f"Search root is not a directory: {search_root}")
+    if shutil.which("git") is None:
+        raise CleanError("Required command not found: git")
+
+    target = (organization.lower(), repository.lower())
+    matches: list[Path] = []
+    for current_text, dirs, files in os.walk(search_root, topdown=True):
+        is_repository = ".git" in dirs or ".git" in files
+        dirs[:] = sorted(name for name in dirs if name not in SKIP_DIRS)
+        if not is_repository:
+            continue
+        current = Path(current_text)
+        if target in repository_remotes(current):
+            matches.append(current.resolve())
+
+    unique_matches = sorted(set(matches))
+    full_name = f"{organization}/{repository}"
+    if not unique_matches:
+        raise CleanError(f"No local GitHub repository matched {full_name} under {search_root}.")
+    if len(unique_matches) > 1:
+        paths = "\n".join(f"  - {path}" for path in unique_matches)
+        raise CleanError(f"Multiple local clones matched {full_name}:\n{paths}")
+    return unique_matches[0]
+
+
+def ensure_compose_file(repository: Path) -> None:
+    if not any((repository / name).is_file() for name in COMPOSE_FILES):
+        names = ", ".join(COMPOSE_FILES)
+        raise CleanError(f"No root-level Docker Compose file found in {repository}. Expected one of: {names}")
+
+
+def ensure_docker(repository: Path) -> None:
+    if shutil.which("docker") is None:
+        raise CleanError("Required command not found: docker")
+    require_success(command(["docker", "compose", "version"], cwd=repository), "Docker Compose is unavailable")
+    require_success(
+        command(["docker", "info", "--format", "{{.ServerVersion}}"], cwd=repository),
+        "Docker daemon is not running or is not accessible",
+    )
+
+
+def compose_config(repository: Path) -> dict[str, Any]:
+    output = require_success(
+        command(["docker", "compose", "--profile", "*", "config", "--format", "json"], cwd=repository),
+        "Could not render the Docker Compose configuration",
+    )
+    try:
+        payload = json.loads(output)
+    except json.JSONDecodeError as exc:
+        raise CleanError(f"Docker Compose returned invalid JSON: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise CleanError("Docker Compose returned an unexpected configuration.")
+    return payload
+
+
+def image_namespace(image: str) -> str | None:
+    reference = image.split("@", 1)[0]
+    last_slash = reference.rfind("/")
+    last_colon = reference.rfind(":")
+    if last_colon > last_slash:
+        reference = reference[:last_colon]
+    parts = reference.split("/")
+    if len(parts) < 2:
+        return None
+    first = parts[0]
+    registry_present = "." in first or ":" in first or first.lower() == "localhost"
+    if registry_present:
+        return parts[1].lower() if len(parts) >= 3 else None
+    return first.lower()
+
+
+def organization_images(config: dict[str, Any], organization: str) -> tuple[str, ...]:
+    images: set[str] = set()
+    services = config.get("services", {})
+    if isinstance(services, dict):
+        for service in services.values():
+            if not isinstance(service, dict):
+                continue
+            image = service.get("image")
+            if isinstance(image, str) and image_namespace(image) == organization.lower():
+                images.add(image)
+    return tuple(sorted(images))
+
+
+def volume_sets(config: dict[str, Any]) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    project: set[str] = set()
+    external: set[str] = set()
+    volumes = config.get("volumes", {})
+    if not isinstance(volumes, dict):
+        return (), ()
+    for key, value in volumes.items():
+        details = value if isinstance(value, dict) else {}
+        name = details.get("name", key)
+        if not isinstance(name, str):
+            continue
+        if details.get("external") is True:
+            external.add(name)
+        else:
+            project.add(name)
+    return tuple(sorted(project)), tuple(sorted(external))
+
+
+def configured_ports(config: dict[str, Any]) -> tuple[str, ...]:
+    """Return every host port declared by every service, including profiled services."""
+    found: set[str] = set()
+    services = config.get("services", {})
+    if not isinstance(services, dict):
+        return ()
+    for service in services.values():
+        if not isinstance(service, dict):
+            continue
+        ports = service.get("ports", [])
+        if not isinstance(ports, list):
+            continue
+        for port in ports:
+            if not isinstance(port, dict) or port.get("published") in (None, ""):
+                continue
+            host_ip = port.get("host_ip") or "0.0.0.0"
+            protocol = port.get("protocol") or "tcp"
+            target = port.get("target")
+            destination = f"->{target}/{protocol}" if target not in (None, "") else ""
+            found.add(f"{host_ip}:{port['published']}{destination}")
+    return tuple(sorted(found))
+
+
+def compose_container_ids(repository: Path) -> tuple[str, ...]:
+    output = require_success(
+        command(["docker", "compose", "--profile", "*", "ps", "--all", "--quiet"], cwd=repository),
+        "Could not list Docker Compose containers",
+    )
+    return tuple(line.strip() for line in output.splitlines() if line.strip())
+
+
+def published_ports(network_settings: Any) -> tuple[str, ...]:
+    found: set[str] = set()
+    if not isinstance(network_settings, dict):
+        return ()
+    ports = network_settings.get("Ports", {})
+    if not isinstance(ports, dict):
+        return ()
+    for container_port, bindings in ports.items():
+        if not isinstance(bindings, list):
+            continue
+        for binding in bindings:
+            if not isinstance(binding, dict) or not binding.get("HostPort"):
+                continue
+            host_ip = binding.get("HostIp") or "0.0.0.0"
+            found.add(f"{host_ip}:{binding['HostPort']}->{container_port}")
+    return tuple(sorted(found))
+
+
+def inspect_containers(container_ids: tuple[str, ...]) -> tuple[ContainerInfo, ...]:
+    if not container_ids:
+        return ()
+    output = require_success(command(["docker", "inspect", *container_ids]), "Could not inspect Compose containers")
+    try:
+        payload = json.loads(output)
+    except json.JSONDecodeError as exc:
+        raise CleanError(f"Docker inspect returned invalid JSON: {exc}") from exc
+    containers: list[ContainerInfo] = []
+    for item in payload:
+        if not isinstance(item, dict):
+            continue
+        config = item.get("Config") if isinstance(item.get("Config"), dict) else {}
+        mounted_volumes = {
+            str(mount.get("Name"))
+            for mount in item.get("Mounts", [])
+            if isinstance(mount, dict) and mount.get("Type") == "volume" and mount.get("Name")
+        }
+        containers.append(
+            ContainerInfo(
+                container_id=str(item.get("Id", "")),
+                name=str(item.get("Name", "")).lstrip("/"),
+                image=str(config.get("Image", "")),
+                ports=published_ports(item.get("NetworkSettings")),
+                volumes=tuple(sorted(mounted_volumes)),
+            )
+        )
+    return tuple(sorted(containers, key=lambda item: item.name))
+
+
+def dangling_volumes() -> tuple[str, ...]:
+    output = require_success(
+        command(["docker", "volume", "ls", "--quiet", "--filter", "dangling=true"]),
+        "Could not list dangling Docker volumes",
+    )
+    return tuple(sorted({line.strip() for line in output.splitlines() if line.strip()}))
+
+
+def local_images(images: tuple[str, ...]) -> tuple[str, ...]:
+    found: list[str] = []
+    for image in images:
+        result = command(["docker", "image", "inspect", image])
+        if result.returncode == 0:
+            found.append(image)
+    return tuple(found)
+
+
+def create_plan(repository: Path, organization: str) -> CleanupPlan:
+    config = compose_config(repository)
+    project_name = str(config.get("name") or repository.name)
+    images = organization_images(config, organization)
+    project_volumes, external_volumes = volume_sets(config)
+    ids = compose_container_ids(repository)
+    containers = inspect_containers(ids)
+    attached_volumes = {name for container in containers for name in container.volumes}
+    removable_volumes = (set(project_volumes) | attached_volumes) - set(external_volumes)
+    return CleanupPlan(
+        repository=repository,
+        project_name=project_name,
+        containers=containers,
+        declared_ports=configured_ports(config),
+        project_volumes=tuple(sorted(removable_volumes)),
+        external_volumes=external_volumes,
+        dangling_volumes=dangling_volumes(),
+        organization_images=images,
+        local_organization_images=local_images(images),
+    )
+
+
+def display_items(label: str, items: Sequence[str]) -> None:
+    print(f"{label}:")
+    if not items:
+        print("  (none)")
+        return
+    for item in items:
+        print(f"  - {item}")
+
+
+def display_plan(plan: CleanupPlan, execute: bool) -> None:
+    print(f"Mode: {'execute' if execute else 'preview'}")
+    print(f"Repository: {plan.repository}")
+    print(f"Compose project: {plan.project_name}")
+    container_lines = []
+    ports: set[str] = set()
+    for container in plan.containers:
+        container_lines.append(f"{container.name or container.container_id[:12]} ({container.image})")
+        ports.update(container.ports)
+    ports.update(plan.declared_ports)
+    display_items("Compose containers to stop and remove", container_lines)
+    display_items("Published ports to free", sorted(ports))
+    display_items("Compose volumes to remove", plan.project_volumes)
+    display_items("External Compose volumes to preserve", plan.external_volumes)
+    dangling = [name for name in plan.dangling_volumes if name not in set(plan.external_volumes)]
+    display_items("Dangling volumes to remove", dangling)
+    display_items("Organization images referenced by Compose", plan.organization_images)
+    display_items("Local organization images to remove", plan.local_organization_images)
+
+
+def execute_plan(plan: CleanupPlan) -> list[str]:
+    failures: list[str] = []
+    down = command(
+        ["docker", "compose", "--profile", "*", "down", "--volumes", "--remove-orphans"],
+        cwd=plan.repository,
+    )
+    if down.returncode != 0:
+        failures.append(f"Compose shutdown failed: {down.stderr or down.stdout or down.returncode}")
+
+    try:
+        current_dangling = dangling_volumes()
+    except CleanError as exc:
+        failures.append(str(exc))
+        current_dangling = ()
+    protected = set(plan.external_volumes)
+    for volume in current_dangling:
+        if volume in protected:
+            continue
+        result = command(["docker", "volume", "rm", volume])
+        if result.returncode != 0:
+            failures.append(f"Could not remove volume {volume}: {result.stderr or result.stdout or result.returncode}")
+
+    for image in plan.local_organization_images:
+        result = command(["docker", "image", "rm", "--force", image])
+        if result.returncode != 0:
+            failures.append(f"Could not remove image {image}: {result.stderr or result.stdout or result.returncode}")
+    return failures
+
+
+def run(args: argparse.Namespace) -> int:
+    repository = find_repository(args.root, args.organization, args.repository)
+    ensure_compose_file(repository)
+    ensure_docker(repository)
+    plan = create_plan(repository, args.organization)
+    display_plan(plan, execute=not args.dry_run)
+    if args.dry_run:
+        print("\nDry run complete. No Docker resources were changed.")
+        return 0
+
+    failures = execute_plan(plan)
+    if failures:
+        print("\nCleanup completed with errors:", file=sys.stderr)
+        for failure in failures:
+            print(f"  - {failure}", file=sys.stderr)
+        return 1
+    print("\nCleanup completed successfully.")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return run(args)
+    except CleanError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\nInterrupted.", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

clean_to_execute-0.0.1/tests/test_clean_to_execute.py

@@ -0,0 +1,296 @@
+import argparse
+import importlib.util
+import io
+import json
+import sys
+import tempfile
+import unittest
+from contextlib import redirect_stderr, redirect_stdout
+from pathlib import Path
+from unittest import mock
+
+
+MODULE_PATH = Path(__file__).parents[1] / "src" / "clean_to_execute.py"
+SPEC = importlib.util.spec_from_file_location("clean_to_execute", MODULE_PATH)
+clean = importlib.util.module_from_spec(SPEC)
+assert SPEC.loader is not None
+sys.modules[SPEC.name] = clean
+SPEC.loader.exec_module(clean)
+
+
+def result(args, returncode=0, stdout="", stderr=""):
+    return clean.CommandResult(tuple(args), returncode, stdout, stderr)
+
+
+class ArgumentTests(unittest.TestCase):
+    def test_required_arguments_and_cleanup_default(self):
+        args = clean.build_parser().parse_args(["--organization", "Kaizten", "--repository", "tools"])
+        self.assertEqual(args.organization, "Kaizten")
+        self.assertEqual(args.repository, "tools")
+        self.assertFalse(args.dry_run)
+
+    def test_yes_argument_is_not_supported(self):
+        with redirect_stderr(io.StringIO()), self.assertRaises(SystemExit) as raised:
+            clean.build_parser().parse_args(["--organization", "kaizten", "--repository", "tools", "--yes"])
+        self.assertEqual(raised.exception.code, 2)
+
+    def test_invalid_name_is_rejected(self):
+        with redirect_stderr(io.StringIO()), self.assertRaises(SystemExit):
+            clean.build_parser().parse_args(["--organization", "bad/name", "--repository", "tools"])
+
+
+class DiscoveryTests(unittest.TestCase):
+    def test_normalize_github_remote(self):
+        self.assertEqual(clean.normalize_github_remote("git@github.com:Kaizten/Tools.git"), ("kaizten", "tools"))
+        self.assertEqual(
+            clean.normalize_github_remote("https://github.com/Kaizten/Tools.git"),
+            ("kaizten", "tools"),
+        )
+        self.assertEqual(
+            clean.normalize_github_remote("ssh://git@github.com/Kaizten/Tools.git"),
+            ("kaizten", "tools"),
+        )
+        self.assertIsNone(clean.normalize_github_remote("https://gitlab.com/Kaizten/Tools.git"))
+
+    def test_find_repository_matches_remote_and_ignores_node_modules(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            wanted = root / "nested" / "checkout"
+            ignored = root / "node_modules" / "copy"
+            (wanted / ".git").mkdir(parents=True)
+            (ignored / ".git").mkdir(parents=True)
+
+            def remotes(path):
+                return {("kaizten", "tools")} if path in {wanted, ignored} else set()
+
+            with mock.patch.object(clean.shutil, "which", return_value="/usr/bin/git"), mock.patch.object(
+                clean, "repository_remotes", side_effect=remotes
+            ):
+                found = clean.find_repository(root, "KAIZTEN", "TOOLS")
+        self.assertEqual(found, wanted)
+
+    def test_find_repository_reports_duplicates(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            for name in ("one", "two"):
+                (root / name / ".git").mkdir(parents=True)
+            with mock.patch.object(clean.shutil, "which", return_value="git"), mock.patch.object(
+                clean, "repository_remotes", return_value={("kaizten", "tools")}
+            ):
+                with self.assertRaisesRegex(clean.CleanError, "Multiple local clones"):
+                    clean.find_repository(root, "kaizten", "tools")
+
+    def test_find_repository_reports_missing_match(self):
+        with tempfile.TemporaryDirectory() as directory, mock.patch.object(clean.shutil, "which", return_value="git"):
+            with self.assertRaisesRegex(clean.CleanError, "No local GitHub repository matched"):
+                clean.find_repository(Path(directory), "kaizten", "missing")
+
+
+class ComposeParsingTests(unittest.TestCase):
+    def test_image_namespace_across_registries(self):
+        cases = {
+            "kaizten/api:latest": "kaizten",
+            "docker.io/kaizten/api:1": "kaizten",
+            "ghcr.io/Kaizten/api@sha256:abc": "kaizten",
+            "localhost:5000/kaizten/team/api": "kaizten",
+            "postgres:17": None,
+            "ghcr.io/postgres": None,
+        }
+        for reference, expected in cases.items():
+            with self.subTest(reference=reference):
+                self.assertEqual(clean.image_namespace(reference), expected)
+
+    def test_organization_images_excludes_other_namespaces(self):
+        config = {
+            "services": {
+                "api": {"image": "ghcr.io/kaizten/api:latest"},
+                "worker": {"image": "kaizten/worker:1"},
+                "similar": {"image": "ghcr.io/kaizten-labs/api:latest"},
+                "db": {"image": "postgres:17"},
+            }
+        }
+        self.assertEqual(
+            clean.organization_images(config, "Kaizten"),
+            ("ghcr.io/kaizten/api:latest", "kaizten/worker:1"),
+        )
+
+    def test_volume_sets_separates_external_volumes(self):
+        config = {
+            "volumes": {
+                "data": {"name": "project_data"},
+                "shared": {"name": "company_shared", "external": True},
+                "cache": None,
+            }
+        }
+        project, external = clean.volume_sets(config)
+        self.assertEqual(project, ("cache", "project_data"))
+        self.assertEqual(external, ("company_shared",))
+
+    def test_published_ports_formats_bindings(self):
+        settings = {
+            "Ports": {
+                "80/tcp": [{"HostIp": "127.0.0.1", "HostPort": "8080"}],
+                "443/tcp": [{"HostIp": "", "HostPort": "8443"}],
+                "9000/tcp": None,
+            }
+        }
+        self.assertEqual(
+            clean.published_ports(settings),
+            ("0.0.0.0:8443->443/tcp", "127.0.0.1:8080->80/tcp"),
+        )
+
+    def test_configured_ports_includes_services_behind_profiles(self):
+        config = {
+            "services": {
+                "frontend": {
+                    "profiles": ["full"],
+                    "ports": [{"target": 80, "published": "80", "protocol": "tcp", "mode": "ingress"}],
+                },
+                "backend": {
+                    "profiles": ["back-end", "full"],
+                    "ports": [
+                        {
+                            "target": 8080,
+                            "published": "8080",
+                            "host_ip": "127.0.0.1",
+                            "protocol": "tcp",
+                        }
+                    ],
+                },
+            }
+        }
+        self.assertEqual(
+            clean.configured_ports(config),
+            ("0.0.0.0:80->80/tcp", "127.0.0.1:8080->8080/tcp"),
+        )
+
+    def test_inspect_containers_includes_anonymous_and_named_volume_mounts(self):
+        payload = [
+            {
+                "Id": "abc",
+                "Name": "/demo-api-1",
+                "Config": {"Image": "kaizten/api"},
+                "NetworkSettings": {"Ports": {}},
+                "Mounts": [
+                    {"Type": "volume", "Name": "demo_data"},
+                    {"Type": "bind", "Source": "/tmp/source"},
+                    {"Type": "volume", "Name": "anonymous-id"},
+                ],
+            }
+        ]
+        with mock.patch.object(clean, "command", return_value=result([], stdout=json.dumps(payload))):
+            containers = clean.inspect_containers(("abc",))
+        self.assertEqual(containers[0].volumes, ("anonymous-id", "demo_data"))
+
+
+class WorkflowTests(unittest.TestCase):
+    def make_plan(self, repository: Path):
+        return clean.CleanupPlan(
+            repository=repository,
+            project_name="demo",
+            containers=(clean.ContainerInfo("abc", "demo-api-1", "kaizten/api", ("0.0.0.0:8080->80/tcp",)),),
+            declared_ports=("0.0.0.0:80->80/tcp",),
+            project_volumes=("demo_data",),
+            external_volumes=("shared",),
+            dangling_volumes=("old", "shared"),
+            organization_images=("kaizten/api",),
+            local_organization_images=("kaizten/api",),
+        )
+
+    def test_dry_run_performs_no_cleanup(self):
+        args = argparse.Namespace(organization="kaizten", repository="tools", root=Path("~"), dry_run=True)
+        plan = self.make_plan(Path("/repo"))
+        with mock.patch.object(clean, "find_repository", return_value=Path("/repo")), mock.patch.object(
+            clean, "ensure_compose_file"
+        ), mock.patch.object(clean, "ensure_docker"), mock.patch.object(
+            clean, "create_plan", return_value=plan
+        ), mock.patch.object(clean, "execute_plan") as execute, redirect_stdout(io.StringIO()) as output:
+            status = clean.run(args)
+        self.assertEqual(status, 0)
+        execute.assert_not_called()
+        self.assertIn("Dry run complete", output.getvalue())
+
+    def test_default_invocation_executes_cleanup(self):
+        args = argparse.Namespace(organization="kaizten", repository="tools", root=Path("~"), dry_run=False)
+        plan = self.make_plan(Path("/repo"))
+        with mock.patch.object(clean, "find_repository", return_value=Path("/repo")), mock.patch.object(
+            clean, "ensure_compose_file"
+        ), mock.patch.object(clean, "ensure_docker"), mock.patch.object(
+            clean, "create_plan", return_value=plan
+        ), mock.patch.object(clean, "execute_plan", return_value=[]) as execute, redirect_stdout(io.StringIO()):
+            status = clean.run(args)
+        self.assertEqual(status, 0)
+        execute.assert_called_once_with(plan)
+
+    def test_execute_uses_compose_down_preserves_external_and_forces_images(self):
+        plan = self.make_plan(Path("/repo"))
+        calls = []
+
+        def fake_command(args, cwd=None):
+            calls.append((tuple(args), cwd))
+            return result(args)
+
+        with mock.patch.object(clean, "command", side_effect=fake_command), mock.patch.object(
+            clean, "dangling_volumes", return_value=("old", "shared", "new")
+        ):
+            failures = clean.execute_plan(plan)
+
+        self.assertEqual(failures, [])
+        self.assertIn(
+            (("docker", "compose", "--profile", "*", "down", "--volumes", "--remove-orphans")),
+            [item[0] for item in calls],
+        )
+        self.assertIn(("docker", "volume", "rm", "old"), [item[0] for item in calls])
+        self.assertIn(("docker", "volume", "rm", "new"), [item[0] for item in calls])
+        self.assertNotIn(("docker", "volume", "rm", "shared"), [item[0] for item in calls])
+        self.assertIn(("docker", "image", "rm", "--force", "kaizten/api"), [item[0] for item in calls])
+
+    def test_execute_aggregates_failures_and_continues(self):
+        plan = self.make_plan(Path("/repo"))
+
+        def fake_command(args, cwd=None):
+            if args[1:2] == ["compose"] and "down" in args:
+                return result(args, 1, stderr="down failed")
+            if args[1:3] == ["volume", "rm"]:
+                return result(args, 1, stderr="volume failed")
+            if args[1:3] == ["image", "rm"]:
+                return result(args, 1, stderr="image failed")
+            return result(args)
+
+        with mock.patch.object(clean, "command", side_effect=fake_command), mock.patch.object(
+            clean, "dangling_volumes", return_value=("old",)
+        ):
+            failures = clean.execute_plan(plan)
+        self.assertEqual(len(failures), 3)
+
+    def test_main_reports_clean_error(self):
+        with mock.patch.object(clean, "run", side_effect=clean.CleanError("broken")), redirect_stderr(
+            io.StringIO()
+        ) as error:
+            status = clean.main(["--organization", "kaizten", "--repository", "tools"])
+        self.assertEqual(status, 1)
+        self.assertIn("Error: broken", error.getvalue())
+
+    def test_compose_config_rejects_invalid_json(self):
+        with mock.patch.object(clean, "command", return_value=result([], stdout="not-json")):
+            with self.assertRaisesRegex(clean.CleanError, "invalid JSON"):
+                clean.compose_config(Path("/repo"))
+
+    def test_compose_inspection_activates_all_profiles(self):
+        with mock.patch.object(clean, "command", return_value=result([], stdout='{"services": {}}')) as run_command:
+            clean.compose_config(Path("/repo"))
+        self.assertEqual(
+            run_command.call_args.args[0],
+            ["docker", "compose", "--profile", "*", "config", "--format", "json"],
+        )
+
+        with mock.patch.object(clean, "command", return_value=result([], stdout="")) as run_command:
+            clean.compose_container_ids(Path("/repo"))
+        self.assertEqual(
+            run_command.call_args.args[0],
+            ["docker", "compose", "--profile", "*", "ps", "--all", "--quiet"],
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()