squarepeg 0.1.0__tar.gz

squarepeg-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: squarepeg
+Version: 0.1.0
+Summary: Run a docker-run-style command as a Kubernetes Pod or Job, streaming its output like a local process
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: kubernetes>=31
+Requires-Dist: PyYAML>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+
+# squarepeg
+
+Run a `docker run`-style command as a Kubernetes Pod or Job, streaming its
+output like a local process and exiting with the container's exit code.
+
+```
+squarepeg run alpine echo "hello from a pod"
+```
+
+## Install
+
+```
+pip install squarepeg
+```
+
+## Docs
+
+Full documentation lives in the [wiki](https://github.com/BioWilko/squarepeg/wiki):
+
+- [Getting Started](https://github.com/BioWilko/squarepeg/wiki/Getting-Started)
+- [CLI Reference](https://github.com/BioWilko/squarepeg/wiki/CLI-Reference)
+- [Configuration](https://github.com/BioWilko/squarepeg/wiki/Configuration)
+- [Environment Variable Interpolation](https://github.com/BioWilko/squarepeg/wiki/Environment-Variable-Interpolation)
+- [Docker Compatibility](https://github.com/BioWilko/squarepeg/wiki/Docker-Compatibility)
+- [Execution Lifecycle](https://github.com/BioWilko/squarepeg/wiki/Execution-Lifecycle)
+- [Troubleshooting](https://github.com/BioWilko/squarepeg/wiki/Troubleshooting)
+- [Development](https://github.com/BioWilko/squarepeg/wiki/Development)
+
+See also [`examples/config.yaml`](examples/config.yaml) for a fully worked
+config file.
+
+## Development
+
+```
+pytest                        # unit tests
+pytest -m integration         # integration tests, requires SQUAREPEG_INTEGRATION=1 and a kind cluster
+ruff check .                  # lint
+```

squarepeg-0.1.0/README.md

@@ -0,0 +1,38 @@
+# squarepeg
+
+Run a `docker run`-style command as a Kubernetes Pod or Job, streaming its
+output like a local process and exiting with the container's exit code.
+
+```
+squarepeg run alpine echo "hello from a pod"
+```
+
+## Install
+
+```
+pip install squarepeg
+```
+
+## Docs
+
+Full documentation lives in the [wiki](https://github.com/BioWilko/squarepeg/wiki):
+
+- [Getting Started](https://github.com/BioWilko/squarepeg/wiki/Getting-Started)
+- [CLI Reference](https://github.com/BioWilko/squarepeg/wiki/CLI-Reference)
+- [Configuration](https://github.com/BioWilko/squarepeg/wiki/Configuration)
+- [Environment Variable Interpolation](https://github.com/BioWilko/squarepeg/wiki/Environment-Variable-Interpolation)
+- [Docker Compatibility](https://github.com/BioWilko/squarepeg/wiki/Docker-Compatibility)
+- [Execution Lifecycle](https://github.com/BioWilko/squarepeg/wiki/Execution-Lifecycle)
+- [Troubleshooting](https://github.com/BioWilko/squarepeg/wiki/Troubleshooting)
+- [Development](https://github.com/BioWilko/squarepeg/wiki/Development)
+
+See also [`examples/config.yaml`](examples/config.yaml) for a fully worked
+config file.
+
+## Development
+
+```
+pytest                        # unit tests
+pytest -m integration         # integration tests, requires SQUAREPEG_INTEGRATION=1 and a kind cluster
+ruff check .                  # lint
+```

squarepeg-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "squarepeg"
+version = "0.1.0"
+description = "Run a docker-run-style command as a Kubernetes Pod or Job, streaming its output like a local process"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.1",
+    "kubernetes>=31",
+    "PyYAML>=6",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.4",
+]
+
+[project.scripts]
+squarepeg = "squarepeg.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["squarepeg*"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: requires a reachable kubernetes cluster (opt in with SQUAREPEG_INTEGRATION=1)",
+]
+addopts = "-m 'not integration'"

squarepeg-0.1.0/setup.cfg

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

squarepeg-0.1.0/squarepeg/__init__.py

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

squarepeg-0.1.0/squarepeg/__main__.py

@@ -0,0 +1,4 @@
+from squarepeg.cli import main
+
+if __name__ == "__main__":
+    main()

squarepeg-0.1.0/squarepeg/cli.py

@@ -0,0 +1,345 @@
+import click
+import yaml
+
+from squarepeg import __version__
+from squarepeg.config import coerce_bool, coerce_int, load_effective_config, select_profile
+from squarepeg.dockerargs import check_supported_image, parse_env_entries, reject_unsupported
+from squarepeg.errors import SquarepegError, UsageError
+from squarepeg.k8s.dryrun import server_dry_run
+from squarepeg.k8s.runner import run_manifest
+from squarepeg.k8s.session import Session
+from squarepeg.manifest import build_job, build_pod
+from squarepeg.naming import generate_name, validate_rfc1123
+from squarepeg.quantities import docker_cpus_to_k8s, docker_memory_to_k8s
+from squarepeg.runspec import ResourceSpec, RunSpec
+from squarepeg.volumes import auto_mounts_from_config, parse_volume_flag
+
+_CONFIG_OPTIONS = [
+    click.option(
+        "--config", "config_paths", multiple=True, type=click.Path(), help="repeatable, layered left-to-right"
+    ),
+    click.option("--no-default-config", "no_default_config", is_flag=True),
+    click.option("--profile", "profile", default=None),
+]
+
+
+def _add_config_options(cmd):
+    for option in _CONFIG_OPTIONS:
+        cmd = option(cmd)
+    return cmd
+
+
+def _resolve_config(config_paths, no_default_config, profile):
+    effective, sources = load_effective_config(config_paths, no_default_config=no_default_config)
+    resolved = select_profile(effective, profile)
+    return resolved, sources
+
+
+def _unsupported_callback(ctx, param, value):
+    if value:
+        reject_unsupported(param.opts[0])
+    return value
+
+
+# flag names -> whether the flag takes a value (False) or is a boolean switch (True)
+_UNSUPPORTED_GROUPS: list[tuple[list[str], bool]] = [
+    (["--network"], False),
+    (["--privileged"], True),
+    (["--gpus"], False),
+    (["-p", "--publish"], False),
+    (["-d", "--detach"], True),
+    (["--restart"], False),
+    (["-u", "--user"], False),
+    (["--mount"], False),
+    (["--cap-add"], False),
+    (["--cap-drop"], False),
+    (["--add-host"], False),
+    (["--link"], False),
+    (["--platform"], False),
+    (["--env-file"], False),
+    (["--hostname"], False),
+    (["--tmpfs"], False),
+]
+
+
+def _add_unsupported_options(cmd):
+    for flag_names, is_flag in _UNSUPPORTED_GROUPS:
+        cmd = click.option(
+            *flag_names,
+            is_flag=is_flag,
+            hidden=True,
+            expose_value=False,
+            callback=_unsupported_callback,
+        )(cmd)
+    return cmd
+
+
+@click.group()
+@click.version_option(__version__, prog_name="squarepeg")
+def cli():
+    """Run a docker-run-style command as a Kubernetes Pod or Job."""
+
+
+@cli.command(
+    context_settings={"allow_interspersed_args": False, "ignore_unknown_options": True},
+)
+@click.option("-e", "--env", "env_entries", multiple=True, help="KEY=VALUE, repeatable")
+@click.option("-v", "--volume", "volume_entries", multiple=True, help="[NAME|/host]:/container[:ro|rw], repeatable")
+@click.option("--name", "name", default=None, help="Pod/Job name")
+@click.option("-w", "--workdir", "workdir", default=None)
+@click.option("--entrypoint", "entrypoint", default=None, help="Override the image ENTRYPOINT (-> k8s 'command')")
+@click.option("-i", "--interactive", "interactive", is_flag=True, help="accepted; stdin is not forwarded")
+@click.option("-t", "--tty", "tty", is_flag=True)
+@click.option("--rm", "rm_flag", is_flag=True, help="accepted no-op; cleanup is already the default")
+@click.option("--pull", "pull", type=click.Choice(["always", "missing", "never"]), default=None)
+@click.option("--cpus", "cpus", default=None)
+@click.option("-m", "--memory", "memory", default=None)
+@click.option("--request-cpu", "request_cpu", default=None)
+@click.option("--limit-cpu", "limit_cpu", default=None)
+@click.option("--request-memory", "request_memory", default=None)
+@click.option("--limit-memory", "limit_memory", default=None)
+@click.option("--mode", "mode", type=click.Choice(["pod", "job"]), default=None)
+@click.option("-n", "--namespace", "namespace", default=None)
+@click.option("--keep", "keep", is_flag=True, help="do not delete the pod/job after it finishes")
+@click.option("--dry-run", "dry_run", is_flag=True, help="render the manifest without creating it")
+@click.option(
+    "--dry-run-server",
+    "dry_run_server",
+    is_flag=True,
+    help="like --dry-run, but additionally validates the manifest against the apiserver",
+)
+@click.option("--timeout", "timeout", type=int, default=None)
+@click.option("--quiet", "quiet", is_flag=True)
+@click.option("--context", "context", default=None, help="kubeconfig context to use")
+@click.option("--container-name", "container_name", default="main")
+@click.argument("image")
+@click.argument("command", nargs=-1, type=click.UNPROCESSED)
+@_add_config_options
+@_add_unsupported_options
+def run(
+    env_entries,
+    volume_entries,
+    name,
+    workdir,
+    entrypoint,
+    interactive,
+    tty,
+    rm_flag,
+    pull,
+    cpus,
+    memory,
+    request_cpu,
+    limit_cpu,
+    request_memory,
+    limit_memory,
+    mode,
+    namespace,
+    keep,
+    dry_run,
+    dry_run_server,
+    config_paths,
+    no_default_config,
+    profile,
+    timeout,
+    quiet,
+    context,
+    container_name,
+    image,
+    command,
+):
+    """Run IMAGE [COMMAND...] as a Kubernetes Pod or Job."""
+    check_supported_image(image)
+    if rm_flag and keep:
+        raise UsageError("--rm and --keep are mutually exclusive")
+    if dry_run and dry_run_server:
+        raise UsageError("--dry-run and --dry-run-server are mutually exclusive")
+
+    resolved_config, _sources = _resolve_config(config_paths, no_default_config, profile)
+    config_defaults = resolved_config.get("defaults") or {}
+    config_volumes = resolved_config.get("volumes") or {}
+    allow_host_path_mounts = coerce_bool(resolved_config.get("allow_host_path_mounts", False), "allow_host_path_mounts")
+
+    claims: set[str] = set()
+
+    env = {**config_defaults.get("env", {}), **parse_env_entries(env_entries)}
+    for key in parse_env_entries(env_entries):
+        claims.add(f"/spec/containers/[name={container_name}]/env/[name={key}]")
+
+    cli_volumes = [
+        parse_volume_flag(v, config_volumes=config_volumes, allow_host_path_mounts=allow_host_path_mounts)
+        for v in volume_entries
+    ]
+    for vol in cli_volumes:
+        claims.add(f"/spec/volumes/[name={vol.volume_name}]")
+        claims.add(f"/spec/containers/[name={container_name}]/volumeMounts/[name={vol.volume_name}]")
+
+    # config-declared auto-mounts (volumes.NAME with a mount_path) are not claimed -- they're
+    # config-driven, not CLI-driven, so kubernetes.spec passthrough in the same config can still
+    # override them, same as any other config default (e.g. defaults.cpus).
+    volumes = auto_mounts_from_config(config_volumes) + cli_volumes
+
+    resources = ResourceSpec()
+    cli_set_cpus, cli_set_memory = cpus is not None, memory is not None
+    if cpus is None and "cpus" in config_defaults:
+        cpus = config_defaults["cpus"]
+    if memory is None and "memory" in config_defaults:
+        memory = config_defaults["memory"]
+    if cpus is not None:
+        converted = docker_cpus_to_k8s(cpus)
+        resources.request_cpu = converted
+        resources.limit_cpu = converted
+    if memory is not None:
+        converted = docker_memory_to_k8s(memory)
+        resources.request_memory = converted
+        resources.limit_memory = converted
+    if request_cpu is not None:
+        resources.request_cpu = request_cpu
+        claims.add(f"/spec/containers/[name={container_name}]/resources/requests/cpu")
+    if limit_cpu is not None:
+        resources.limit_cpu = limit_cpu
+        claims.add(f"/spec/containers/[name={container_name}]/resources/limits/cpu")
+    if request_memory is not None:
+        resources.request_memory = request_memory
+        claims.add(f"/spec/containers/[name={container_name}]/resources/requests/memory")
+    if limit_memory is not None:
+        resources.limit_memory = limit_memory
+        claims.add(f"/spec/containers/[name={container_name}]/resources/limits/memory")
+    if cli_set_cpus and request_cpu is None:
+        claims.add(f"/spec/containers/[name={container_name}]/resources/requests/cpu")
+    if cli_set_cpus and limit_cpu is None:
+        claims.add(f"/spec/containers/[name={container_name}]/resources/limits/cpu")
+    if cli_set_memory and request_memory is None:
+        claims.add(f"/spec/containers/[name={container_name}]/resources/requests/memory")
+    if cli_set_memory and limit_memory is None:
+        claims.add(f"/spec/containers/[name={container_name}]/resources/limits/memory")
+
+    if name is not None:
+        validate_rfc1123(name, what="--name")
+        claims.add("/metadata/name")
+    else:
+        name = generate_name(image)
+
+    if namespace is not None:
+        claims.add("/metadata/namespace")
+    else:
+        namespace = resolved_config.get("namespace")
+
+    pull_policy = {"always": "Always", "missing": "IfNotPresent", "never": "Never"}.get(pull) if pull else None
+    if pull_policy is not None:
+        claims.add(f"/spec/containers/[name={container_name}]/imagePullPolicy")
+    elif "image_pull_policy" in config_defaults:
+        pull_policy = config_defaults["image_pull_policy"]
+
+    if workdir is not None:
+        claims.add(f"/spec/containers/[name={container_name}]/workingDir")
+    elif "workdir" in config_defaults:
+        workdir = config_defaults["workdir"]
+
+    mode = mode or resolved_config.get("mode", "pod")
+    timeout = timeout if timeout is not None else coerce_int(resolved_config.get("timeout", 300), "timeout")
+    quiet = quiet or coerce_bool(resolved_config.get("quiet", False), "quiet")
+    cleanup = False if keep else coerce_bool(resolved_config.get("cleanup", True), "cleanup")
+    orphan_sweep = coerce_bool(resolved_config.get("orphan_sweep", True), "orphan_sweep")
+    orphan_sweep_min_age = coerce_int(resolved_config.get("orphan_sweep_min_age", 300), "orphan_sweep_min_age")
+    if orphan_sweep_min_age < 0:
+        raise UsageError(f"'orphan_sweep_min_age' must not be negative, got {orphan_sweep_min_age}")
+
+    entrypoint_tuple = (entrypoint,) if entrypoint is not None else None
+    if entrypoint_tuple is not None:
+        claims.add(f"/spec/containers/[name={container_name}]/command")
+    if command:
+        claims.add(f"/spec/containers/[name={container_name}]/args")
+
+    if tty:
+        claims.add(f"/spec/containers/[name={container_name}]/tty")
+        if not interactive:
+            # some clusters reject tty=true with stdin=false; -i is accepted but never
+            # forwards real stdin, so this can hang a container that then blocks reading it.
+            click.echo(
+                "squarepeg: -t implies stdin is opened on the container (stdinOnce), but stdin is "
+                "never actually forwarded; a process that blocks reading stdin will hang. Pass -i "
+                "explicitly to acknowledge this.",
+                err=True,
+            )
+            interactive = True
+    if interactive:
+        claims.add(f"/spec/containers/[name={container_name}]/stdin")
+
+    spec = RunSpec(
+        image=image,
+        args=tuple(command),
+        entrypoint=entrypoint_tuple,
+        env=env,
+        workdir=workdir,
+        volumes=volumes,
+        tty=tty,
+        stdin=interactive,
+        pull_policy=pull_policy,
+        mode=mode,
+        namespace=namespace,
+        name=name,
+        container_name=container_name,
+        resources=resources,
+        cleanup=cleanup,
+        timeout=timeout,
+        quiet=quiet,
+        orphan_sweep=orphan_sweep,
+        orphan_sweep_min_age=orphan_sweep_min_age,
+        claims=claims,
+    )
+
+    kubernetes_passthrough = resolved_config.get("kubernetes")
+    job_passthrough = resolved_config.get("job")
+    if spec.mode == "job":
+        manifest = build_job(spec, kubernetes_passthrough, job_passthrough)
+    else:
+        manifest = build_pod(spec, kubernetes_passthrough)
+
+    if dry_run_server:
+        session = Session(namespace=spec.namespace, context=context, quiet=spec.quiet)
+        spec.namespace = session.namespace
+        validated = server_dry_run(session, spec, manifest)
+        click.echo(yaml.safe_dump(validated, sort_keys=False), nl=False)
+        return
+    if dry_run:
+        click.echo(yaml.safe_dump(manifest, sort_keys=False), nl=False)
+        return
+
+    session = Session(namespace=spec.namespace, context=context, quiet=spec.quiet)
+    spec.namespace = session.namespace
+    exit_code = run_manifest(session, spec, manifest)
+    raise SystemExit(exit_code)
+
+
+@cli.group("config")
+def config_group():
+    """Inspect the resolved config."""
+
+
+@config_group.command("show")
+@_add_config_options
+def config_show(config_paths, no_default_config, profile):
+    """Print the merged effective config (stdout) and its sources (stderr)."""
+    resolved_config, sources = _resolve_config(config_paths, no_default_config, profile)
+    for path, origin in sources:
+        click.echo(f"[squarepeg] {path} ({origin})", err=True)
+    if not sources:
+        click.echo("[squarepeg] no config files loaded", err=True)
+    click.echo(yaml.safe_dump(resolved_config, sort_keys=False), nl=False)
+
+
+def main():
+    try:
+        cli(standalone_mode=False)
+    except click.ClickException as exc:
+        exc.show()
+        raise SystemExit(exc.exit_code) from exc
+    except click.exceptions.Exit as exc:
+        raise SystemExit(exc.exit_code) from exc
+    except SquarepegError as exc:
+        click.echo(f"squarepeg: {exc}", err=True)
+        raise SystemExit(exc.exit_code) from exc
+
+
+if __name__ == "__main__":
+    main()

squarepeg-0.1.0/squarepeg/config.py

@@ -0,0 +1,190 @@
+"""Nextflow-style layered config loading.
+
+Resolution order, lowest to highest precedence:
+  1. built-in defaults (not a file; handled by callers)
+  2. the single default path ~/.config/squarepeg/config.yaml, if present
+  3. $SQUAREPEG_CONFIG: a colon-separated list of paths, left-to-right
+  4. each --config PATH given on the CLI, in order, left-to-right
+  5. individual CLI flags (applied by callers, not here)
+
+Every file in 2-4 is merged with the same key-level deep_merge used for k8s
+passthrough (with an empty claim set) -- see merge.py for why whole-file
+override would defeat the point of layering.
+"""
+
+import os
+from pathlib import Path
+
+import yaml
+
+from squarepeg.env_interpolation import interpolate_document
+from squarepeg.errors import ConfigError
+from squarepeg.merge import deep_merge
+
+ENV_VAR = "SQUAREPEG_CONFIG"
+DEFAULT_CONFIG_PATH = Path.home() / ".config" / "squarepeg" / "config.yaml"
+
+ALLOWED_TOP_KEYS = {
+    "namespace",
+    "mode",
+    "cleanup",
+    "timeout",
+    "quiet",
+    "allow_host_path_mounts",
+    "split_streams",
+    "orphan_sweep",
+    "orphan_sweep_min_age",
+    "defaults",
+    "volumes",
+    "kubernetes",
+    "job",
+    "profiles",
+}
+ALLOWED_DEFAULTS_KEYS = {"cpus", "memory", "image_pull_policy", "workdir", "env"}
+
+
+def _resolve_env_paths() -> list[tuple[Path, str]]:
+    raw = os.environ.get(ENV_VAR, "")
+    resolved = []
+    for segment in raw.split(":"):
+        if not segment:
+            continue
+        path = Path(segment).expanduser()
+        if not path.exists():
+            raise ConfigError(f"config file {path} (from ${ENV_VAR}) does not exist")
+        resolved.append((path, f"${ENV_VAR}"))
+    return resolved
+
+
+def _resolve_cli_paths(cli_config_paths: tuple[str, ...]) -> list[tuple[Path, str]]:
+    resolved = []
+    for raw in cli_config_paths:
+        path = Path(raw).expanduser()
+        if not path.exists():
+            raise ConfigError(f"config file {path} (from --config {raw}) does not exist")
+        resolved.append((path, f"--config {raw}"))
+    return resolved
+
+
+def resolve_config_sources(
+    cli_config_paths: tuple[str, ...] = (), *, no_default_config: bool = False
+) -> list[tuple[Path, str]]:
+    """Return [(path, origin_label)] in the order they should be merged, lowest precedence first."""
+    sources: list[tuple[Path, str]] = []
+    if not no_default_config and DEFAULT_CONFIG_PATH.exists():
+        sources.append((DEFAULT_CONFIG_PATH, "default location"))
+    sources.extend(_resolve_env_paths())
+    sources.extend(_resolve_cli_paths(cli_config_paths))
+    return sources
+
+
+def load_yaml_document(path: Path) -> dict:
+    try:
+        text = path.read_text()
+    except OSError as exc:
+        raise ConfigError(f"cannot read config file {path}: {exc}") from exc
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"malformed YAML in {path}: {exc}") from exc
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ConfigError(f"config file {path} must be a YAML mapping at the top level")
+    return data
+
+
+def validate_document(doc: dict, source: str, *, allow_profiles: bool = True) -> None:
+    for key in doc:
+        if key not in ALLOWED_TOP_KEYS:
+            raise ConfigError(f"unknown config key {key!r} in {source}")
+    defaults = doc.get("defaults")
+    if defaults:
+        for key in defaults:
+            if key not in ALLOWED_DEFAULTS_KEYS:
+                raise ConfigError(f"unknown key 'defaults.{key}' in {source}")
+    profiles = doc.get("profiles")
+    if profiles:
+        if not allow_profiles:
+            raise ConfigError(f"nested 'profiles' is not allowed inside a profile (in {source})")
+        for name, body in profiles.items():
+            if not isinstance(body, dict):
+                raise ConfigError(f"profile {name!r} in {source} must be a mapping")
+            validate_document(body, f"{source} (profile {name!r})", allow_profiles=False)
+    volumes = doc.get("volumes")
+    if volumes:
+        if not isinstance(volumes, dict):
+            raise ConfigError(f"'volumes' in {source} must be a mapping")
+        for name, entry in volumes.items():
+            if not isinstance(entry, dict):
+                raise ConfigError(f"volume {name!r} in {source} must be a mapping")
+            # squarepeg only validates its own keys here; the rest of the entry is an
+            # opaque k8s volume source (persistentVolumeClaim, emptyDir, ...) that the
+            # apiserver validates -- same exemption as the 'kubernetes'/'job' sections.
+            if "mount_path" in entry:
+                mount_path = entry["mount_path"]
+                if not isinstance(mount_path, str) or not mount_path.startswith("/"):
+                    raise ConfigError(
+                        f"volumes.{name}.mount_path in {source} must be an absolute container "
+                        f"path (got {mount_path!r})"
+                    )
+            if "read_only" in entry:
+                coerce_bool(entry["read_only"], f"volumes.{name}.read_only (in {source})")
+
+
+def load_effective_config(
+    cli_config_paths: tuple[str, ...] = (), *, no_default_config: bool = False
+) -> tuple[dict, list[tuple[Path, str]]]:
+    """Load and merge every config layer. Returns (effective_config, sources)."""
+    sources = resolve_config_sources(cli_config_paths, no_default_config=no_default_config)
+    effective: dict = {}
+    for path, origin in sources:
+        source = f"{path} ({origin})"
+        doc = load_yaml_document(path)
+        doc = interpolate_document(doc, source)
+        validate_document(doc, source)
+        effective = deep_merge(effective, doc)
+    return effective, sources
+
+
+_TRUE_STRINGS = {"true", "1", "yes", "on"}
+_FALSE_STRINGS = {"false", "0", "no", "off"}
+
+
+def coerce_int(value, key: str) -> int:
+    """Coerce a config value to int, accepting an int-looking string (e.g. from ${VAR} interpolation)."""
+    if isinstance(value, bool):  # bool is an int subclass; reject it explicitly
+        raise ConfigError(f"expected an integer for {key!r}, got {value!r}")
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        try:
+            return int(value.strip())
+        except ValueError:
+            pass
+    raise ConfigError(f"expected an integer for {key!r}, got {value!r}")
+
+
+def coerce_bool(value, key: str) -> bool:
+    """Coerce a config value to bool, accepting a bool-looking string (e.g. from ${VAR} interpolation)."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in _TRUE_STRINGS:
+            return True
+        if lowered in _FALSE_STRINGS:
+            return False
+    raise ConfigError(f"expected a boolean for {key!r}, got {value!r}")
+
+
+def select_profile(effective_config: dict, profile_name: str | None) -> dict:
+    """Fold the named profile over the rest of the effective config (L1+L2)."""
+    if profile_name is None:
+        return {k: v for k, v in effective_config.items() if k != "profiles"}
+    profiles = effective_config.get("profiles") or {}
+    if profile_name not in profiles:
+        available = ", ".join(sorted(profiles)) or "(none defined)"
+        raise ConfigError(f"unknown profile {profile_name!r}; available profiles: {available}")
+    base = {k: v for k, v in effective_config.items() if k != "profiles"}
+    return deep_merge(base, profiles[profile_name])