phx-paddock 0.1.0__py3-none-any.whl

paddock/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

paddock/__main__.py

@@ -0,0 +1,94 @@
+import logging
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from paddock.agents import BaseAgent, agent_registry
+from paddock.cli import parse_args
+from paddock.config.loader import ConfigLoader
+from paddock.docker.build import ImageBuilder
+from paddock.docker.builder import DockerCommandBuilder
+
+logger = logging.getLogger("paddock")
+
+
+def _setup_logging(quiet: bool) -> None:
+    if quiet:
+        logging.disable(logging.CRITICAL)
+    else:
+        logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+
+def _log_network_peers(network: str) -> None:
+    """Log names of other containers running on the same network."""
+    result = subprocess.run(
+        ["docker", "ps", "--filter", f"network={network}", "--format={{.Names}}"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0 and result.stdout.strip():
+        for name in result.stdout.strip().splitlines():
+            logger.info("  - %s", name)
+
+
+def run(argv: list[str] | None = None) -> None:
+    parsed = parse_args(argv if argv is not None else sys.argv[1:])
+    _setup_logging(parsed.quiet)
+
+    workdir = Path(parsed.workdir) if parsed.workdir else Path.cwd()
+
+    loader = ConfigLoader()
+    runner = loader.resolve(parsed, workdir, environ=dict(os.environ))
+
+    if not runner.is_valid():
+        for key, errors in runner.errors.items():
+            for error in errors:
+                print(f"Config error [{key}]: {error}", file=sys.stderr)
+        sys.exit(1)
+
+    config = runner.cleaned_data
+
+    agent_key = "false" if config["agent"] is False else str(config["agent"])
+    agent: BaseAgent = agent_registry.get(agent_key)
+
+    logger.info("Using image: %s", config["image"])
+    logger.info("Agent: %s", config["agent"])
+    for host, container in config["volumes"].items():
+        logger.info("Mounting %s -> %s", host, container)
+    if config.get("network"):
+        logger.info("Network: %s", config["network"])
+        logger.info("Other containers on this network:")
+        _log_network_peers(config["network"])
+
+    if config.get("build"):
+        builder = ImageBuilder()
+        build_args = {**agent.get_build_args(), **config["build"].get("args", {})}
+        built = builder.maybe_build(
+            build_config=config["build"],
+            image=config["image"],
+            build_args=build_args,
+        )
+        logger.info("Image build: %s", "triggered" if built else "skipped (up to date)")
+
+    docker_argv = DockerCommandBuilder(
+        config=config,
+        agent=agent,
+        workdir=workdir,
+    ).build(command=parsed.command)
+
+    if not parsed.quiet:
+        print(" ".join(docker_argv))
+
+    if parsed.dry_run:
+        sys.exit(0)
+
+    subprocess.run(docker_argv)
+
+
+def main() -> None:
+    run()
+
+
+if __name__ == "__main__":
+    main()

paddock/agents/__init__.py

@@ -0,0 +1,46 @@
+from abc import ABC, abstractmethod
+from typing import ClassVar
+
+from class_registry.entry_points import EntryPointClassRegistry
+
+agent_registry: EntryPointClassRegistry = EntryPointClassRegistry("paddock.agents")
+
+
+class BaseAgent(ABC):
+    AGENT_KEY: ClassVar[str]
+
+    @abstractmethod
+    def get_command(self) -> list[str]:
+        """
+        Default command to run in the container.
+
+        Example: ['claude'] for ClaudeAgent, ['/bin/bash'] for ShellAgent.
+        """
+
+    @abstractmethod
+    def get_volumes(self) -> dict[str, str]:
+        """
+        Host-path-keyed volume mounts specific to this agent.
+
+        Values are '/container/path' or '/container/path:mode'.
+        Example: {'/home/user/.claude': '/root/.claude:rw'}
+        """
+
+    def get_scratch_volumes(self, image: str) -> dict[str, str]:
+        """
+        Named Docker volumes (not host paths) to create and mount.
+
+        Keys are volume names, values are container paths. Override when the agent
+        needs persistent storage that must not be shared with the host.
+        Example: {'paddock_ubuntu_22_04_claude': '/scratch'}
+        """
+        return {}
+
+    def get_build_args(self) -> dict[str, str]:
+        """
+        Docker build args to pass when building the paddock base image.
+
+        Used when the built-in Dockerfile is referenced in the build config.
+        Example: {'AGENT': 'claude'}
+        """
+        return {}

paddock/agents/claude.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+
+from paddock.agents import BaseAgent
+
+
+class ClaudeAgent(BaseAgent):
+    AGENT_KEY = "claude"
+
+    def get_command(self) -> list[str]:
+        return ["claude"]
+
+    def get_volumes(self) -> dict[str, str]:
+        return {str(Path.home() / ".claude"): "/root/.claude:rw"}
+
+    def get_build_args(self) -> dict[str, str]:
+        return {"AGENT": "claude"}

paddock/agents/shell.py

@@ -0,0 +1,14 @@
+from paddock.agents import BaseAgent
+
+
+class ShellAgent(BaseAgent):
+    AGENT_KEY = "false"
+
+    def get_command(self) -> list[str]:
+        return ["/bin/bash"]
+
+    def get_volumes(self) -> dict[str, str]:
+        return {}
+
+    def get_build_args(self) -> dict[str, str]:
+        return {"AGENT": "none"}

paddock/cli.py

@@ -0,0 +1,148 @@
+import argparse
+from dataclasses import dataclass
+
+_KNOWN_BOOL_FLAGS = frozenset({"--dry-run", "--quiet"})
+_KNOWN_VALUE_FLAGS = frozenset(
+    {
+        "--agent",
+        "--build-context",
+        "--build-dockerfile",
+        "--build-policy",
+        "--config-file",
+        "--image",
+        "--network",
+        "--volume",
+        "--workdir",
+    }
+)
+
+
+@dataclass
+class ParsedArgs:
+    agent: str | bool | None
+    build_args: dict[str, str]
+    build_context: str | None
+    build_dockerfile: str | None
+    build_policy: str | None
+    command: list[str]
+    config_file: str | None
+    dry_run: bool
+    image: str | None
+    network: str | None
+    quiet: bool
+    volumes: dict[str, str]
+    workdir: str | None
+
+
+def _split_argv(argv: list[str]) -> tuple[list[str], list[str]]:
+    """
+    Split argv into (paddock_flags, container_command).
+
+    Scans left-to-right collecting known paddock flags. Stops at:
+    - '--' (explicit split, consumed): rest becomes the command
+    - A non-flag token (positional): this token and everything after become the command
+
+    Unknown flags (starting with '--' but not in the known set) remain in
+    paddock_flags so argparse can report them as errors.
+    """
+    paddock: list[str] = []
+    i = 0
+    while i < len(argv):
+        token = argv[i]
+
+        if token == "--":
+            return paddock, argv[i + 1 :]
+
+        if token in _KNOWN_BOOL_FLAGS:
+            paddock.append(token)
+            i += 1
+            continue
+
+        flag = token.split("=", 1)[0]
+        if flag in _KNOWN_VALUE_FLAGS or flag.startswith("--build-args-"):
+            paddock.append(token)
+            if "=" not in token:
+                i += 1
+                if i < len(argv):
+                    paddock.append(argv[i])
+            i += 1
+            continue
+
+        if token.startswith("-"):
+            # Unknown flag — leave in paddock so argparse exits with an error.
+            paddock.append(token)
+            i += 1
+            continue
+
+        # Positional — this token and everything after is the container command.
+        return paddock, argv[i:]
+
+    return paddock, []
+
+
+def _parse_volume(value: str) -> tuple[str, str]:
+    """
+    Parse '--volume=/host:/container[:mode]' into (host_path, container_spec).
+
+    Intentionally does not use the Volume filter — the CLI format separates
+    host and container paths with ':', whereas TOML stores them as separate fields.
+    """
+    host, _, rest = value.partition(":")
+    return host, rest
+
+
+def parse_args(argv: list[str]) -> ParsedArgs:
+    """
+    Parse paddock CLI arguments.
+
+    Stops consuming paddock flags at the first positional arg or '--'. Unknown
+    flags before either stop-point are errors. '--' is consumed; everything
+    after it becomes the container command, preserving any subsequent '--'.
+    """
+    paddock_argv, command = _split_argv(argv)
+
+    # Extract --build-args-<key>=<value> entries before argparse sees them.
+    build_args: dict[str, str] = {}
+    filtered: list[str] = []
+    for entry in paddock_argv:
+        if entry.startswith("--build-args-") and "=" in entry:
+            raw_key, _, val = entry[len("--build-args-") :].partition("=")
+            build_args[raw_key.replace("-", "_")] = val
+        else:
+            filtered.append(entry)
+
+    parser = argparse.ArgumentParser(prog="paddock", add_help=True)
+    parser.add_argument("--agent")
+    parser.add_argument("--build-context")
+    parser.add_argument("--build-dockerfile")
+    parser.add_argument("--build-policy")
+    parser.add_argument("--config-file")
+    parser.add_argument("--dry-run", action="store_true", default=False)
+    parser.add_argument("--image")
+    parser.add_argument("--network")
+    parser.add_argument("--quiet", action="store_true", default=False)
+    parser.add_argument("--volume", action="append", default=[])
+    parser.add_argument("--workdir")
+
+    namespace = parser.parse_args(filtered)
+
+    volumes: dict[str, str] = {}
+    for vol in namespace.volume:
+        host, rest = _parse_volume(vol)
+        volumes[host] = rest
+
+    return ParsedArgs(
+        agent=namespace.agent,
+        build_args=build_args,
+        build_context=namespace.build_context,
+        build_dockerfile=namespace.build_dockerfile,
+        build_policy=namespace.build_policy,
+        command=command,
+        config_file=namespace.config_file,
+        dry_run=namespace.dry_run,
+        image=namespace.image,
+        network=namespace.network,
+        quiet=namespace.quiet,
+        volumes=volumes,
+        workdir=namespace.workdir,
+    )

paddock/config/filters.py

@@ -0,0 +1,71 @@
+import filters as f
+from filters.base import BaseFilter
+
+
+class Agent(BaseFilter):
+    """Validates a coding agent value.
+
+    Accepts a non-empty string agent name, or ``False`` to disable the agent.
+    Maps the string ``'false'`` to boolean ``False``. Rejects boolean ``True``.
+    """
+
+    CODE_INVALID = "invalid"
+
+    templates = {
+        CODE_INVALID: "Expected a non-empty agent name string, or False.",
+    }
+
+    def _apply(self, value):
+        # Boolean True is always invalid.
+        if value is True:
+            return self._invalid_value(value, self.CODE_INVALID)
+
+        # Boolean False passes through directly.
+        if value is False:
+            return False
+
+        # Map the string 'false' to boolean False.
+        if isinstance(value, str) and value == "false":
+            return False
+
+        # Non-empty string agent names are valid.
+        value = self._filter(value, f.Unicode | f.NotEmpty)
+        if self._has_errors:
+            return None
+
+        return value
+
+
+class Volume(BaseFilter):
+    """Validates a Docker volume container path.
+
+    Accepts paths of the form ``/container/path``, ``/container/path:ro``,
+    or ``/container/path:rw``. Values with more than one colon-separated
+    segment are invalid.
+    """
+
+    CODE_INVALID = "invalid"
+
+    templates = {
+        CODE_INVALID: "Expected a container path, optionally suffixed with :ro or :rw.",
+    }
+
+    def _apply(self, value):
+        value = self._filter(value, f.Unicode)
+        if self._has_errors:
+            return None
+
+        # Values with more than one colon are invalid.
+        parts = value.split(":")
+        if len(parts) > 2:
+            return self._invalid_value(value, self.CODE_INVALID)
+
+        # If a mode suffix is present, it must be 'ro' or 'rw'.
+        if len(parts) == 2 and parts[1] not in ("ro", "rw"):
+            return self._invalid_value(value, self.CODE_INVALID)
+
+        # Bare paths (no mode suffix) are normalised to read-only.
+        if len(parts) == 1:
+            return value + ":ro"
+
+        return value

paddock/config/loader.py

@@ -0,0 +1,353 @@
+import tomllib
+from pathlib import Path
+from typing import Any, TypedDict
+
+import filters as f
+
+from paddock.config.schema import _config_schema
+
+_USER_CONFIG_PATH = Path.home() / ".config" / "paddock" / "config.toml"
+_PROJECT_CONFIG_NAME = Path(".paddock") / "config.toml"
+
+
+class ConfigEntry(TypedDict):
+    """A single config value annotated with its origin."""
+
+    value: Any
+    source: str
+
+
+# SourcedConfig: same shape as the config schema, but leaf values are ConfigEntry.
+SourcedConfig = dict[str, Any]
+
+
+class ConfigLoader:
+    """Loads, merges, and validates paddock config from all sources.
+
+    Config resolution order (later sources overwrite earlier):
+
+    1. User-level (``~/.config/paddock/config.toml``)
+    2. Project-level (``<workdir>/.paddock/config.toml``)
+    3. Extra config file via ``PADDOCK_CONFIG_FILE`` env var
+    4. Extra config file via ``--config-file`` CLI arg
+    5. Env var overrides (``PADDOCK_*``)
+    6. CLI arg overrides
+    """
+
+    def load_user_config(self, path: Path = _USER_CONFIG_PATH) -> SourcedConfig:
+        """Load the user-level config file.
+
+        Args:
+            path:
+
+                Path to the user config file. Defaults to
+                ``~/.config/paddock/config.toml``.
+
+        Returns:
+            A ``SourcedConfig`` mapping, or ``{}`` if the file does not exist.
+        """
+        return self._load_toml_sourced(path)
+
+    def load_project_config(self, workdir: Path) -> SourcedConfig:
+        """Load the project-level config from ``<workdir>/.paddock/config.toml``.
+
+        Args:
+            workdir:
+
+                The project working directory.
+
+        Returns:
+            A ``SourcedConfig`` mapping, or ``{}`` if the file does not exist.
+        """
+        return self._load_toml_sourced(workdir / _PROJECT_CONFIG_NAME)
+
+    def load_extra_config(self, path: Path) -> SourcedConfig:
+        """Load an arbitrary config file (for ``PADDOCK_CONFIG_FILE`` or ``--config-file``).
+
+        Args:
+            path:
+
+                Path to the extra config file.
+
+        Returns:
+            A ``SourcedConfig`` mapping, or ``{}`` if the file does not exist.
+        """
+        return self._load_toml_sourced(path)
+
+    def config_from_env(self, environ: dict[str, str]) -> SourcedConfig:
+        """Extract config from ``PADDOCK_*`` environment variables.
+
+        Strips the ``PADDOCK_`` prefix, lowercases, and splits on ``_`` to map
+        to the config structure. For example::
+
+            PADDOCK_IMAGE=foo           → {'image': {'value': 'foo', ...}}
+            PADDOCK_BUILD_DOCKERFILE=x  → {'build': {'dockerfile': {'value': 'x', ...}}}
+
+        Args:
+            environ:
+
+                Environment variable mapping to inspect.
+
+        Returns:
+            A ``SourcedConfig`` containing only the ``PADDOCK_``-prefixed entries.
+        """
+        config: SourcedConfig = {}
+        prefix = "PADDOCK_"
+        for key, value in environ.items():
+            if not key.startswith(prefix):
+                continue
+            parts = key[len(prefix) :].lower().split("_")
+            self._deep_set_sourced(config, parts, value, source=f"env:{key}")
+        return config
+
+    def config_from_cli(self, parsed: Any) -> SourcedConfig:
+        """Extract config from a parsed CLI args object (omitting ``None`` values).
+
+        Args:
+            parsed:
+
+                An object with attributes matching the paddock CLI argument names.
+
+        Returns:
+            A ``SourcedConfig`` containing only the non-``None`` CLI values.
+        """
+        config: SourcedConfig = {}
+        build: SourcedConfig = {}
+        source = "cli"
+
+        if parsed.image is not None:
+            config["image"] = {"value": parsed.image, "source": source}
+        if parsed.agent is not None:
+            config["agent"] = {"value": parsed.agent, "source": source}
+        if parsed.network is not None:
+            config["network"] = {"value": parsed.network, "source": source}
+        if parsed.build_dockerfile is not None:
+            build["dockerfile"] = {"value": parsed.build_dockerfile, "source": source}
+        if parsed.build_context is not None:
+            build["context"] = {"value": parsed.build_context, "source": source}
+        if parsed.build_policy is not None:
+            build["policy"] = {"value": parsed.build_policy, "source": source}
+        if parsed.build_args:
+            build["args"] = {
+                k: {"value": v, "source": source} for k, v in parsed.build_args.items()
+            }
+        if build:
+            config["build"] = build
+        if parsed.volumes:
+            config["volumes"] = {
+                k: {"value": v, "source": source} for k, v in parsed.volumes.items()
+            }
+        return config
+
+    def resolve(
+        self,
+        parsed: Any,
+        workdir: Path,
+        environ: dict[str, str] | None = None,
+    ) -> f.FilterRunner:
+        """Load config from all sources, merge, apply defaults, and validate.
+
+        Args:
+            parsed:
+
+                Parsed CLI arguments object.
+
+            workdir:
+
+                The project working directory.
+
+            environ:
+
+                Environment variable mapping. Defaults to ``os.environ``.
+
+        Returns:
+            A ``FilterRunner`` for the caller to check ``is_valid()``.
+        """
+        import os
+
+        env = environ if environ is not None else dict(os.environ)
+
+        sources = [
+            self.load_user_config(),
+            self.load_project_config(workdir),
+        ]
+
+        if paddock_config_file := env.get("PADDOCK_CONFIG_FILE"):
+            sources.append(self.load_extra_config(Path(paddock_config_file)))
+
+        if parsed.config_file is not None:
+            sources.append(self.load_extra_config(Path(parsed.config_file)))
+
+        sources.append(self.config_from_env(env))
+        sources.append(self.config_from_cli(parsed))
+
+        merged_sourced = self._merge_sourced(sources)
+        plain = self._extract_values(merged_sourced)
+        plain = self._apply_defaults(plain)
+
+        return f.FilterRunner(_config_schema, plain)
+
+    def _load_toml_sourced(self, path: Path) -> SourcedConfig:
+        """Load a TOML file and wrap each leaf value with its source path.
+
+        Args:
+            path:
+
+                Path to the TOML file.
+
+        Returns:
+            A ``SourcedConfig``, or ``{}`` if the file does not exist.
+        """
+        if not path.exists():
+            return {}
+        with path.open("rb") as fh:
+            raw = tomllib.load(fh)
+        return self._annotate_source(raw, str(path))
+
+    def _annotate_source(self, data: dict, source: str) -> SourcedConfig:
+        """Recursively wrap leaf values with source info.
+
+        Args:
+            data:
+
+                Raw config dict to annotate.
+
+            source:
+
+                Source label (typically a file path string).
+
+        Returns:
+            A ``SourcedConfig`` with the same structure as ``data``.
+        """
+        result: SourcedConfig = {}
+        for key, value in data.items():
+            if isinstance(value, dict):
+                result[key] = self._annotate_source(value, source)
+            else:
+                result[key] = {"value": value, "source": source}
+        return result
+
+    def _deep_set_sourced(
+        self,
+        config: SourcedConfig,
+        parts: list[str],
+        value: str,
+        source: str,
+    ) -> None:
+        """Deep-set a value in a ``SourcedConfig`` using a key-path list.
+
+        Args:
+            config:
+
+                The target ``SourcedConfig`` to mutate.
+
+            parts:
+
+                Ordered key segments forming the path to the target leaf.
+
+            value:
+
+                The raw string value to store.
+
+            source:
+
+                Source label for the ``ConfigEntry``.
+        """
+        node = config
+        for part in parts[:-1]:
+            if part not in node or not isinstance(node[part], dict):
+                node[part] = {}
+            node = node[part]
+        node[parts[-1]] = {"value": value, "source": source}
+
+    def _merge_sourced(self, sources: list[SourcedConfig]) -> SourcedConfig:
+        """Deep-merge a list of ``SourcedConfig`` dicts; later sources overwrite earlier.
+
+        Args:
+            sources:
+
+                Ordered list of ``SourcedConfig`` mappings.
+
+        Returns:
+            A single merged ``SourcedConfig``.
+        """
+        result: SourcedConfig = {}
+        for source in sources:
+            result = self._deep_merge(result, source)
+        return result
+
+    def _deep_merge(self, base: dict, override: dict) -> dict:
+        """Recursively merge ``override`` into ``base``.
+
+        ``ConfigEntry`` dicts (those with both ``value`` and ``source`` keys) are
+        treated as leaves and replaced wholesale rather than merged.
+
+        Args:
+            base:
+
+                The base dict to merge into.
+
+            override:
+
+                The dict whose values take precedence.
+
+        Returns:
+            A new merged dict.
+        """
+        result = dict(base)
+        for key, value in override.items():
+            if (
+                key in result
+                and isinstance(result[key], dict)
+                and isinstance(value, dict)
+                and not ("value" in value and "source" in value)
+            ):
+                result[key] = self._deep_merge(result[key], value)
+            else:
+                result[key] = value
+        return result
+
+    def _extract_values(self, sourced: SourcedConfig) -> dict:
+        """Strip source annotations, returning a plain config dict.
+
+        Args:
+            sourced:
+
+                A ``SourcedConfig`` to strip.
+
+        Returns:
+            A plain dict with the same structure but without ``ConfigEntry`` wrappers.
+        """
+        result: dict = {}
+        for key, value in sourced.items():
+            if isinstance(value, dict):
+                if "value" in value and "source" in value:
+                    result[key] = value["value"]
+                else:
+                    result[key] = self._extract_values(value)
+            else:
+                result[key] = value
+        return result
+
+    def _apply_defaults(self, config: dict) -> dict:
+        """Apply default values for omitted config keys.
+
+        Mutates and returns ``config``.
+
+        Args:
+            config:
+
+                The plain config dict to fill.
+
+        Returns:
+            The same dict with defaults applied.
+        """
+        config.setdefault("agent", "claude")
+        config.setdefault("build", None)
+        config.setdefault("network", None)
+        config.setdefault("volumes", {})
+        if isinstance(config.get("build"), dict):
+            config["build"].setdefault("args", {})
+            config["build"].setdefault("context", None)
+            config["build"].setdefault("policy", "if-missing")
+        return config

paddock/config/schema.py

@@ -0,0 +1,61 @@
+import sys
+
+import filters as f
+
+from paddock.config.filters import Agent, Volume
+
+BUILD_POLICIES = ("always", "daily", "if-missing", "weekly")
+
+# Schema for the build sub-dict.
+_build_schema = f.FilterMapper(
+    {
+        "args": f.Optional(None) | f.FilterRepeater(f.Unicode),
+        "context": f.Optional(None),
+        "dockerfile": f.Required | f.Unicode | f.NotEmpty,
+        "policy": f.Optional(None) | f.Choice(BUILD_POLICIES),
+    },
+    allow_extra_keys=False,
+)
+
+# Top-level config schema — exported for use by the loader.
+_config_schema = f.FilterMapper(
+    {
+        "agent": f.Required | Agent,
+        "build": f.Optional(None) | _build_schema,
+        "image": f.Required | f.Unicode | f.NotEmpty,
+        "network": f.Optional(None),
+        "volumes": f.Optional(dict) | f.FilterRepeater(Volume),
+    },
+    allow_extra_keys=False,
+)
+
+
+class ConfigSchema:
+    """Validates a merged paddock config dict.
+
+    Prints errors to stderr and calls ``sys.exit(1)`` on failure.
+    """
+
+    def validate(self, config: dict) -> dict:
+        """Validates the config dict and returns the cleaned result.
+
+        Args:
+            config:
+
+                The raw config mapping to validate.
+
+        Returns:
+            The cleaned and normalised config dict.
+        """
+        runner = f.FilterRunner(_config_schema, config)
+
+        if not runner.is_valid():
+            for key, messages in runner.errors.items():
+                for msg in messages:
+                    print(
+                        f"Config error [{key}]: {msg['message']}",
+                        file=sys.stderr,
+                    )
+            sys.exit(1)
+
+        return runner.cleaned_data

paddock/docker/build.py

@@ -0,0 +1,92 @@
+import subprocess
+from datetime import datetime, timedelta, timezone
+from enum import StrEnum
+from pathlib import Path
+
+import filters as f
+
+
+class BuildPolicy(StrEnum):
+    ALWAYS = "always"
+    DAILY = "daily"
+    IF_MISSING = "if-missing"
+    WEEKLY = "weekly"
+
+
+class ImageBuilder:
+    @staticmethod
+    def should_build(policy: BuildPolicy, image_created_at: datetime | None) -> bool:
+        """Determine whether to build the image given the policy and current image age."""
+        match policy:
+            case BuildPolicy.ALWAYS:
+                return True
+            case BuildPolicy.IF_MISSING:
+                return image_created_at is None
+            case BuildPolicy.DAILY:
+                if image_created_at is None:
+                    return True
+                return (datetime.now(timezone.utc) - image_created_at) > timedelta(
+                    hours=24
+                )
+            case BuildPolicy.WEEKLY:
+                if image_created_at is None:
+                    return True
+                return (datetime.now(timezone.utc) - image_created_at) > timedelta(
+                    days=7
+                )
+
+    def get_image_created_at(self, image: str) -> datetime | None:
+        """Return the creation timestamp of a local Docker image, or None if absent."""
+        result = subprocess.run(
+            ["docker", "image", "inspect", "--format={{.Created}}", image],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            return None
+        created_str = result.stdout.strip()
+        runner = f.FilterRunner(f.Datetime(), created_str)
+        if not runner.is_valid():
+            return None
+        return runner.cleaned_data
+
+    def run_build(
+        self,
+        *,
+        image: str,
+        dockerfile: str,
+        context: str,
+        build_args: dict[str, str],
+    ) -> None:
+        """Run docker build, streaming output to stdout."""
+        argv = ["docker", "build", "-t", image, "-f", dockerfile]
+        for key, value in build_args.items():
+            argv += ["--build-arg", f"{key}={value}"]
+        argv.append(context)
+        subprocess.run(argv, check=True)
+
+    def maybe_build(
+        self,
+        *,
+        build_config: dict,
+        image: str,
+        build_args: dict[str, str],
+    ) -> bool:
+        """
+        Build the image if the build policy requires it.
+
+        Returns True if a build was triggered, False if skipped.
+        """
+        policy = BuildPolicy(build_config.get("policy", "if-missing"))
+        dockerfile = build_config["dockerfile"]
+        context = build_config.get("context") or str(Path(dockerfile).parent)
+        image_created_at = self.get_image_created_at(image)
+        if self.should_build(policy, image_created_at):
+            self.run_build(
+                image=image,
+                dockerfile=dockerfile,
+                context=context,
+                build_args=build_args,
+            )
+            return True
+        return False

paddock/docker/builder.py

@@ -0,0 +1,65 @@
+import re
+import subprocess
+from pathlib import Path
+
+from paddock.agents import BaseAgent
+
+
+def sanitise_volume_name(image: str, agent_key: str) -> str:
+    """Generate a Docker volume name from image + agent key."""
+    sanitised = re.sub(r"[^a-z0-9]", "_", image.lower())
+    return f"paddock_{sanitised}_{agent_key}"
+
+
+class DockerCommandBuilder:
+    def __init__(self, *, config: dict, agent: BaseAgent, workdir: Path) -> None:
+        self._config = config
+        self._agent = agent
+        self._workdir = workdir
+
+    def build(self, *, command: list[str]) -> list[str]:
+        """Assemble the full 'docker run' argv list."""
+        argv = ["docker", "run", "--rm", "-it"]
+        argv += ["--name", self._resolve_container_name()]
+        argv += [f"--workdir={self._workdir}"]
+        argv += self._volume_flag(str(self._workdir), f"{self._workdir}:rw")
+        for host, container in self._agent.get_volumes().items():
+            argv += self._volume_flag(host, container)
+        for host, container in self._config.get("volumes", {}).items():
+            argv += self._volume_flag(host, container)
+        for vol_name, container_path in self._agent.get_scratch_volumes(
+            self._config["image"]
+        ).items():
+            argv += self._volume_flag(vol_name, container_path)
+        if self._config.get("network"):
+            argv += ["--network", self._config["network"]]
+        argv.append(self._config["image"])
+        argv += command if command else self._agent.get_command()
+        return argv
+
+    def _resolve_container_name(self) -> str:
+        """Derive container name from workdir; append numeric suffix if taken."""
+        dirname = self._workdir.name.lower()
+        agent_key = self._agent.AGENT_KEY
+        base_name = f"paddock-{dirname}-{agent_key}"
+        if self._container_name_available(base_name):
+            return base_name
+        suffix = 1
+        while True:
+            candidate = f"{base_name}-{suffix}"
+            if self._container_name_available(candidate):
+                return candidate
+            suffix += 1
+
+    def _container_name_available(self, name: str) -> bool:
+        """Return True if no running or stopped container has this name."""
+        result = subprocess.run(
+            ["docker", "ps", "-a", "--filter", f"name=^{name}$", "--format={{.Names}}"],
+            capture_output=True,
+            text=True,
+        )
+        return name not in result.stdout.splitlines()
+
+    @staticmethod
+    def _volume_flag(host_or_name: str, container_spec: str) -> list[str]:
+        return ["-v", f"{host_or_name}:{container_spec}"]

phx_paddock-0.1.0.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: phx-paddock
+Version: 0.1.0
+Summary: Launch coding agents in isolated Docker containers.
+Project-URL: Repository, https://github.com/phx/paddock
+Author-email: Phoenix Zerin <phx@phx.nz>
+License-Expression: MIT
+License-File: LICENCE.txt
+Keywords: agents,coding,docker,isolation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: <4,>=3.12
+Requires-Dist: phx-class-registry<6.0.0,>=5.2.1
+Requires-Dist: phx-filters<4.0.0,>=3.5.1
+Description-Content-Type: text/x-rst
+
+paddock
+=======
+
+Launch coding agents (or a plain shell) in isolated Docker containers,
+with the current working directory mounted as the workspace.
+
+.. image:: https://img.shields.io/pypi/v/paddock.svg
+   :target: https://pypi.org/project/paddock/
+   :alt: PyPI version
+
+.. image:: https://img.shields.io/pypi/pyversions/paddock.svg
+   :alt: Python versions
+
+.. image:: https://img.shields.io/badge/licence-MIT-blue.svg
+   :alt: MIT Licence
+
+Overview
+--------
+
+``paddock`` assembles and executes a ``docker run`` command from a layered
+configuration system.  Config is resolved in priority order:
+
+1. User-level TOML  (``~/.config/paddock/config.toml``)
+2. Project-level TOML  (``<workdir>/.paddock/config.toml``)
+3. Extra TOML file via ``PADDOCK_CONFIG_FILE`` env var
+4. Extra TOML file via ``--config-file`` CLI flag
+5. ``PADDOCK_*`` environment variables
+6. CLI flags
+
+Later sources overwrite earlier ones; ``volumes`` entries are additive.
+
+Requirements
+------------
+
+- Python 3.12+
+- Docker (CLI must be available on ``PATH``)
+
+Installation
+------------
+
+.. code-block:: bash
+
+   pip install paddock
+
+Or with `uv <https://github.com/astral-sh/uv>`_:
+
+.. code-block:: bash
+
+   uv tool install paddock
+
+Quick Start
+-----------
+
+Drop into a plain bash shell inside the current directory:
+
+.. code-block:: bash
+
+   paddock --image=ubuntu:24.04 --agent=false
+
+Run Claude Code in an isolated container:
+
+.. code-block:: bash
+
+   paddock --image=my-claude-image --agent=claude
+
+Print the assembled ``docker run`` command without executing it:
+
+.. code-block:: bash
+
+   paddock --image=ubuntu:24.04 --agent=false --dry-run
+
+Configuration
+-------------
+
+TOML files
+~~~~~~~~~~
+
+Place a ``config.toml`` at ``~/.config/paddock/`` (user-level) or
+``<project>/.paddock/`` (project-level).  Both files are optional.
+
+.. code-block:: toml
+
+   agent  = "claude"
+   image  = "my-claude-image:latest"
+   network = "my-docker-network"
+
+   [volumes]
+   "/host/path" = "/container/path:ro"
+
+   [build]
+   dockerfile = "images/Dockerfile"
+   context    = "."
+   policy     = "daily"
+
+   [build.args]
+   AGENT          = "claude"
+   PYTHON_VERSION = "3.13"
+
+Config fields
+~~~~~~~~~~~~~
+
++--------------------+----------------------------+--------------------------------------------------+
+| Field              | Type                       | Description                                      |
++====================+============================+==================================================+
+| ``agent``          | ``string`` or ``false``    | Agent key (``"claude"``) or ``false`` for shell  |
++--------------------+----------------------------+--------------------------------------------------+
+| ``image``          | ``string``                 | Docker image to run (required)                   |
++--------------------+----------------------------+--------------------------------------------------+
+| ``network``        | ``string`` (optional)      | Docker network to attach the container to        |
++--------------------+----------------------------+--------------------------------------------------+
+| ``volumes``        | ``{host: container}`` map  | Extra bind-mounts; container path may end        |
+|                    |                            | in ``:ro`` or ``:rw`` (bare path defaults to     |
+|                    |                            | ``:ro``)                                         |
++--------------------+----------------------------+--------------------------------------------------+
+| ``build``          | sub-table (optional)       | Image auto-build settings (see below)            |
++--------------------+----------------------------+--------------------------------------------------+
+
+Build sub-table
+~~~~~~~~~~~~~~~
+
++----------------+---------------------------------------------+-------------------------------------------+
+| Field          | Type                                        | Description                               |
++================+=============================================+===========================================+
+| ``dockerfile`` | ``string``                                  | Path to the Dockerfile (required if build |
+|                |                                             | table is present)                         |
++----------------+---------------------------------------------+-------------------------------------------+
+| ``context``    | ``string`` (optional)                       | Docker build context path                 |
++----------------+---------------------------------------------+-------------------------------------------+
+| ``policy``     | ``"always"`` / ``"daily"`` /                | When to rebuild the image                 |
+|                | ``"if-missing"`` / ``"weekly"``             |                                           |
++----------------+---------------------------------------------+-------------------------------------------+
+| ``args``       | ``{name: value}`` map (optional)            | Build-time ``--build-arg`` values         |
++----------------+---------------------------------------------+-------------------------------------------+
+
+Environment variables
+~~~~~~~~~~~~~~~~~~~~~
+
+Any config field can be set via an environment variable by uppercasing its
+name and prefixing with ``PADDOCK_``.  Nested keys are joined with ``_``:
+
+.. code-block:: bash
+
+   PADDOCK_IMAGE=ubuntu:24.04
+   PADDOCK_AGENT=claude
+   PADDOCK_BUILD_DOCKERFILE=images/Dockerfile
+   PADDOCK_BUILD_POLICY=daily
+   PADDOCK_CONFIG_FILE=/path/to/extra.toml   # loads an additional TOML file
+
+CLI flags
+~~~~~~~~~
+
+.. code-block:: text
+
+   paddock [FLAGS] [--] [COMMAND...]
+
+   --agent AGENT                Agent key (e.g. "claude") or "false" for a shell
+   --build-args-KEY=VALUE        Build-time ARG (repeatable)
+   --build-context PATH         Docker build context
+   --build-dockerfile PATH      Path to Dockerfile
+   --build-policy POLICY        Build policy (always|daily|if-missing|weekly)
+   --config-file PATH           Load an additional TOML config file
+   --dry-run                    Print the docker command and exit without running it
+   --image IMAGE                Docker image
+   --network NETWORK            Docker network
+   --quiet                      Suppress all logging and the docker command printout
+   --volume HOST:CONTAINER[:MODE]  Extra bind-mount (repeatable)
+   --workdir PATH               Host path to use as the workspace (default: CWD)
+
+Everything after the first positional argument (or after ``--``) is passed
+as the container command:
+
+.. code-block:: bash
+
+   paddock --image=ubuntu:24.04 --agent=false -- bash -c "echo hello"
+
+Agents
+------
+
+``claude``
+~~~~~~~~~~
+
+Runs ``claude`` inside the container.  Mounts ``~/.claude`` from the host
+to ``/root/.claude:rw`` so authentication and configuration persist between
+sessions.
+
+``false`` (shell)
+~~~~~~~~~~~~~~~~~
+
+Runs ``/bin/bash``.  Useful for exploring the container environment or
+running ad-hoc commands without a coding agent.
+
+Adding agents
+~~~~~~~~~~~~~
+
+Additional agents can be registered via the ``paddock.agents`` entry-point
+group in any installed package:
+
+.. code-block:: toml
+
+   [project.entry-points."paddock.agents"]
+   my-agent = "mypackage.agents:MyAgent"
+
+Each agent must subclass ``paddock.agents.BaseAgent`` and implement
+``get_command()`` and ``get_volumes()``.
+
+Docker Image
+------------
+
+A ready-to-use ``Dockerfile`` is included in ``images/``.  It installs
+Python (via the deadsnakes PPA), Node.js, and the selected coding agent.
+
+Build arguments:
+
++--------------------+-------------------+----------------------------------------------+
+| ARG                | Default           | Description                                  |
++====================+===================+==============================================+
+| ``UBUNTU_VERSION`` | ``24.04``         | Ubuntu base image tag                        |
++--------------------+-------------------+----------------------------------------------+
+| ``AGENT``          | ``none``          | ``claude`` or ``none``                       |
++--------------------+-------------------+----------------------------------------------+
+| ``NODE_VERSION``   | ``22``            | Node.js major version                        |
++--------------------+-------------------+----------------------------------------------+
+| ``PYTHON_VERSION`` | ``3.13``          | Python version (installed from deadsnakes)   |
++--------------------+-------------------+----------------------------------------------+
+
+Build the image manually:
+
+.. code-block:: bash
+
+   docker build \
+     --build-arg AGENT=claude \
+     -t my-claude-image \
+     -f images/Dockerfile .
+
+Or set a ``[build]`` table in your config and let paddock build it
+automatically according to your chosen policy.
+
+Licence
+-------
+
+MIT — see ``LICENCE.txt``.

phx_paddock-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+paddock/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+paddock/__main__.py,sha256=xtxndLPFSAF1l9secx6PFPntslF8T4YBKXURjclBplE,2814
+paddock/cli.py,sha256=fMYhYOnxVtPYdBk24-SEYDfqjJd6hVW3bCAW8GME4D8,4577
+paddock/agents/__init__.py,sha256=RHWFXAucLHS8V1bWir3zb1X9pF8-M4WhtQ1p3BO-ZjU,1424
+paddock/agents/claude.py,sha256=osocoPSF_JnmSi7Wn0z2bqt5WZ1qWBtrMhgKQ-a7kvk,383
+paddock/agents/shell.py,sha256=tAJrxb4e6ooGexCY2ST-8sdGWKtb70iNzII2LB49oyU,308
+paddock/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+paddock/config/filters.py,sha256=dJk_FQdWIOX440woE-xc0CN4zOx14Lg_4QHRvGzPrac,2059
+paddock/config/loader.py,sha256=ckq3lZBAY_3QeAQ4826ehymEzWpapcpBY2DmqPLwCW0,10943
+paddock/config/schema.py,sha256=ASdJ3qyphiEg7zNA6XAfa0ebJYgCWqYWcAFpgx_92yg,1689
+paddock/docker/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+paddock/docker/build.py,sha256=CGNGlmmNT91fVuzgrg4LVSnA-WXMH4Z5Z9gRd6aZWaM,3022
+paddock/docker/builder.py,sha256=NcvpQ-82tPnC91fQ63xuCwxfXtkyc1vXulVXg4Ky3BM,2619
+phx_paddock-0.1.0.dist-info/METADATA,sha256=PY_jD-i0age86rnO_T77VDfAzjZrBu_NihonoMXoOZU,9678
+phx_paddock-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+phx_paddock-0.1.0.dist-info/entry_points.txt,sha256=4j-ateD6UnVFJLzat-Nqx1rGGxJ4yv2KnpaELs1Kp04,151
+phx_paddock-0.1.0.dist-info/licenses/LICENCE.txt,sha256=OFw0PwrlgLmgsHneANTra9eoHh3t8GF74MaI5Nm6jaU,1070
+phx_paddock-0.1.0.dist-info/RECORD,,

phx_paddock-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

phx_paddock-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+paddock = paddock.__main__:main
+
+[paddock.agents]
+claude = paddock.agents.claude:ClaudeAgent
+false = paddock.agents.shell:ShellAgent

phx_paddock-0.1.0.dist-info/licenses/LICENCE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phoenix Zerin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.