aetherion 0.1.0__tar.gz

aetherion-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

aetherion-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

aetherion-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sam
+
+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.

aetherion-0.1.0/Makefile

@@ -0,0 +1,18 @@
+.PHONY: help build publish clean
+
+.DEFAULT_GOAL := help
+
+help: ## Show this help
+	@awk 'BEGIN {FS = ":.*## "; print "Available targets:\n"} \
+	      /^[a-zA-Z_-]+:.*## / { printf "  \033[36m%-10s\033[0m %s\n", $$1, $$2 }' \
+	      $(MAKEFILE_LIST)
+
+build: clean ## Build sdist + wheel into dist/
+	uv build
+
+publish: build ## Upload dist/* to PyPI (requires UV_PUBLISH_TOKEN or ~/.pypirc)
+	uv publish
+
+clean: ## Remove build artifacts (dist/, build/, *.egg-info, __pycache__)
+	rm -rf dist/ build/ src/*.egg-info
+	find . -type d -name __pycache__ -not -path './.venv/*' -exec rm -rf {} +

aetherion-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: aetherion
+Version: 0.1.0
+Summary: Dev container launcher for AI coding agents
+License-File: LICENSE
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# Aetherion
+
+A containerized development environment for AI coding agents.
+
+Ships a Debian dev container preloaded with the four major agent CLIs (Claude
+Code, Cursor Agent, GitHub Copilot CLI, Gemini CLI), Neovim with LSP/DAP
+support, podman-in-podman, and toolchains for Python, Node, Go, Rust, and
+Ruby. The `aetherion` launcher mounts the current directory at the same path
+inside the container and preserves per-agent login state across sessions.
+
+## Install
+
+```shell
+uv tool install aetherion
+```
+
+(or `pipx install aetherion`)
+
+## Quickstart
+
+```shell
+aetherion --build-image    # one-time: build localhost/aetherion:dev
+aetherion                  # launch a shell in $PWD
+```
+
+## What's in the container
+
+- **Languages & runtimes**: Python (system + uv), Node (via bun), Go, Rust, Ruby, C/C++ toolchain
+- **Agent CLIs**: Claude Code, Cursor Agent, GitHub Copilot CLI, Gemini CLI
+- **Editor**: Neovim with bundled LSPs (`pyright`, `gopls`, `rust-analyzer`, `lua-language-server`, `typescript-language-server`, `vim-language-server`) and DAPs (`debugpy`, `delve`, `codelldb`, `js-debug-adapter`)
+- **CLI tools**: git, podman, tmux, starship, ripgrep, fd, fzf, jq, yq, posting, openssh-client
+
+## State preservation
+
+The first time you log in to a bundled agent CLI, the launcher detects the new
+config inside the container and copies it to `~/.aetherion/data/` on the host.
+Subsequent launches bind-mount the saved config so you stay logged in.
+`~/.aetherion/data/` is the only host directory the launcher writes to.
+
+| agent | preserved paths |
+| --- | --- |
+| `claude` | `.claude/`, `.claude.json` |
+| `cursor` | `.cursor/`, `.config/cursor/` |
+| `copilot` | `.copilot/` |
+| `gemini` | `.gemini` |
+
+## Flags
+
+| flag | purpose |
+| --- | --- |
+| `--agents LIST` | Comma-separated subset of agents to expose (default: all). `--agents ''` for none. |
+| `-e`, `--env NAME=VALUE` | Set a container environment variable. Repeatable. Quote at the shell for values with spaces: `--env 'NAME=has spaces'`. A bare `--env NAME` inherits from the host environment. |
+| `--image REF` | Image ref to run, and to tag when building. Default: `localhost/aetherion:dev`. |
+| `--build-image` | Build the image and exit. Does not launch the container. |
+| `--build-dir PATH` | Build context directory. Defaults to the Dockerfile bundled with the launcher. |
+| `--extract PATH` | Copy the bundled Dockerfile, skeleton/, and scripts/ to PATH and exit. |
+
+`AETHERION_CONTAINER_RUNTIME=docker` overrides runtime auto-detection (podman is preferred when both are available).
+
+## Customizing the image
+
+The launcher ships its own Dockerfile and skeleton tree inside the Python
+package. To fork them:
+
+```shell
+aetherion --extract ~/my-aetherion
+$EDITOR ~/my-aetherion/Dockerfile
+aetherion --build-image --build-dir ~/my-aetherion --image my:tag
+aetherion --image my:tag
+```
+
+## Development
+
+```shell
+git clone https://github.com/samintheshell/aetherion
+cd aetherion
+uv sync
+uv run aetherion --help
+```
+
+Build and publish the Python package with the included Makefile:
+
+```shell
+make            # show available targets
+make build      # produce sdist + wheel in dist/
+make publish    # upload dist/* to PyPI (UV_PUBLISH_TOKEN required)
+```
+
+The container image itself has `uv` plus the standard CPython toolchain
+installed, so you can also run `make publish` from inside an `aetherion`
+shell if you prefer keeping credentials in the container.

aetherion-0.1.0/README.md

@@ -0,0 +1,91 @@
+# Aetherion
+
+A containerized development environment for AI coding agents.
+
+Ships a Debian dev container preloaded with the four major agent CLIs (Claude
+Code, Cursor Agent, GitHub Copilot CLI, Gemini CLI), Neovim with LSP/DAP
+support, podman-in-podman, and toolchains for Python, Node, Go, Rust, and
+Ruby. The `aetherion` launcher mounts the current directory at the same path
+inside the container and preserves per-agent login state across sessions.
+
+## Install
+
+```shell
+uv tool install aetherion
+```
+
+(or `pipx install aetherion`)
+
+## Quickstart
+
+```shell
+aetherion --build-image    # one-time: build localhost/aetherion:dev
+aetherion                  # launch a shell in $PWD
+```
+
+## What's in the container
+
+- **Languages & runtimes**: Python (system + uv), Node (via bun), Go, Rust, Ruby, C/C++ toolchain
+- **Agent CLIs**: Claude Code, Cursor Agent, GitHub Copilot CLI, Gemini CLI
+- **Editor**: Neovim with bundled LSPs (`pyright`, `gopls`, `rust-analyzer`, `lua-language-server`, `typescript-language-server`, `vim-language-server`) and DAPs (`debugpy`, `delve`, `codelldb`, `js-debug-adapter`)
+- **CLI tools**: git, podman, tmux, starship, ripgrep, fd, fzf, jq, yq, posting, openssh-client
+
+## State preservation
+
+The first time you log in to a bundled agent CLI, the launcher detects the new
+config inside the container and copies it to `~/.aetherion/data/` on the host.
+Subsequent launches bind-mount the saved config so you stay logged in.
+`~/.aetherion/data/` is the only host directory the launcher writes to.
+
+| agent | preserved paths |
+| --- | --- |
+| `claude` | `.claude/`, `.claude.json` |
+| `cursor` | `.cursor/`, `.config/cursor/` |
+| `copilot` | `.copilot/` |
+| `gemini` | `.gemini` |
+
+## Flags
+
+| flag | purpose |
+| --- | --- |
+| `--agents LIST` | Comma-separated subset of agents to expose (default: all). `--agents ''` for none. |
+| `-e`, `--env NAME=VALUE` | Set a container environment variable. Repeatable. Quote at the shell for values with spaces: `--env 'NAME=has spaces'`. A bare `--env NAME` inherits from the host environment. |
+| `--image REF` | Image ref to run, and to tag when building. Default: `localhost/aetherion:dev`. |
+| `--build-image` | Build the image and exit. Does not launch the container. |
+| `--build-dir PATH` | Build context directory. Defaults to the Dockerfile bundled with the launcher. |
+| `--extract PATH` | Copy the bundled Dockerfile, skeleton/, and scripts/ to PATH and exit. |
+
+`AETHERION_CONTAINER_RUNTIME=docker` overrides runtime auto-detection (podman is preferred when both are available).
+
+## Customizing the image
+
+The launcher ships its own Dockerfile and skeleton tree inside the Python
+package. To fork them:
+
+```shell
+aetherion --extract ~/my-aetherion
+$EDITOR ~/my-aetherion/Dockerfile
+aetherion --build-image --build-dir ~/my-aetherion --image my:tag
+aetherion --image my:tag
+```
+
+## Development
+
+```shell
+git clone https://github.com/samintheshell/aetherion
+cd aetherion
+uv sync
+uv run aetherion --help
+```
+
+Build and publish the Python package with the included Makefile:
+
+```shell
+make            # show available targets
+make build      # produce sdist + wheel in dist/
+make publish    # upload dist/* to PyPI (UV_PUBLISH_TOKEN required)
+```
+
+The container image itself has `uv` plus the standard CPython toolchain
+installed, so you can also run `make publish` from inside an `aetherion`
+shell if you prefer keeping credentials in the container.

aetherion-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aetherion"
+version = "0.1.0"
+description = "Dev container launcher for AI coding agents"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = []
+
+[project.scripts]
+aetherion = "aetherion.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aetherion"]

aetherion-0.1.0/src/aetherion/__init__.py

@@ -0,0 +1,3 @@
+"""Aetherion: dev container launcher for AI coding agents."""
+
+__version__ = "0.1.0"

aetherion-0.1.0/src/aetherion/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point for `python -m aetherion`. The console-script entry point in
+pyproject.toml points at the same function, so both invocation paths share
+a single implementation."""
+
+import sys
+
+from aetherion.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

aetherion-0.1.0/src/aetherion/cli.py

@@ -0,0 +1,410 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import os
+import secrets
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+DEFAULT_IMAGE = "localhost/aetherion:dev"
+CONTAINER_HOME = "/home/aetherion"
+
+# Files shipped alongside the launcher that together form the docker build
+# context. Order is purely cosmetic (used in log output).
+BUNDLED_ASSETS: tuple[str, ...] = ("Dockerfile", "skeleton", "scripts")
+
+# Per-agent state we preserve on the host so that login or first-run setup
+# done inside one container session survives into the next. Each tuple lists
+# the paths (relative to CONTAINER_HOME, mirrored under the host data dir)
+# owned by that agent — keep new paths grouped under the agent that owns
+# them so `--agents <name>` slicing keeps working with no extra plumbing.
+AGENT_PATHS: dict[str, tuple[str, ...]] = {
+    "claude":  (".claude", ".claude.json"),
+    "cursor":  (".cursor", ".config/cursor"),
+    "copilot": (".copilot",),
+    "gemini":  (".gemini",),
+}
+
+
+def _detect_runtime() -> str:
+    override = os.environ.get("AETHERION_CONTAINER_RUNTIME")
+    if override:
+        return override
+    for candidate in ("podman", "docker"):
+        if shutil.which(candidate):
+            return candidate
+    sys.stderr.write(
+        "aetherion: container runtime detection failed "
+        "(tried podman and docker, neither found in PATH).\n"
+        "Set AETHERION_CONTAINER_RUNTIME to override.\n"
+    )
+    raise SystemExit(2)
+
+
+# Container runtime: env var overrides; auto-detect prefers podman over docker.
+CONTAINER_RUNTIME = _detect_runtime()
+# Match against the basename so a full path (e.g. /usr/bin/docker) still works.
+_RUNTIME_IS_DOCKER = Path(CONTAINER_RUNTIME).name == "docker"
+
+
+def user_ns_args() -> list[str]:
+    # Podman and Docker diverge on user-namespace handling. Podman's
+    # `keep-id` maps the host UID/GID into the container so bind-mounted
+    # config stays owned by the caller. Docker has no `keep-id`; running as
+    # an explicit uid:gid achieves the equivalent ownership on the mounts.
+    if _RUNTIME_IS_DOCKER:
+        return ["--user", "1000:1000"]
+    return ["--userns=keep-id:uid=1000,gid=1000"]
+
+
+def _bundled_assets_dir() -> Path:
+    # Dockerfile + skeleton/ + scripts/ ship inside the package itself, in a
+    # sibling data/ directory. This resolves to the same real path whether
+    # the launcher runs from a source checkout, an editable install, or a
+    # pip-installed wheel — no importlib.resources dance required, because
+    # we always need real filesystem paths anyway (docker build + shutil
+    # both want them).
+    return Path(__file__).resolve().parent / "data"
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="aetherion",
+        description="Launch the aetherion dev container.",
+    )
+    known = ", ".join(AGENT_PATHS)
+    parser.add_argument(
+        "--agents",
+        metavar="LIST",
+        type=lambda s: [a.strip() for a in s.split(",") if a.strip()],
+        default=list(AGENT_PATHS),
+        help=(
+            "Comma-separated subset of agent toolchains whose login/setup state "
+            "to expose into the container. Anything not listed is neither "
+            f"mounted in nor preserved on exit. Default: all. Known: {known}. "
+            "Pass an empty value (--agents '') to expose nothing."
+        ),
+    )
+    parser.add_argument(
+        "--image",
+        metavar="REF",
+        default=DEFAULT_IMAGE,
+        help=f"Container image to run (and to tag when building). Default: {DEFAULT_IMAGE}.",
+    )
+    parser.add_argument(
+        "--build-image",
+        action="store_true",
+        help=(
+            "Build the image and exit (does not launch the container). Uses "
+            "--build-dir as context if given, otherwise the Dockerfile + "
+            "skeleton bundled with this script. Chain with && to launch after."
+        ),
+    )
+    parser.add_argument(
+        "--build-dir",
+        metavar="PATH",
+        default=None,
+        help=(
+            "Directory to use as the build context. Must contain a Dockerfile. "
+            "Combine with --build-image to build from a customized copy "
+            "(see --extract)."
+        ),
+    )
+    parser.add_argument(
+        "--extract",
+        metavar="PATH",
+        default=None,
+        help=(
+            "Copy the bundled Dockerfile, skeleton/, and scripts/ into PATH "
+            "and exit without launching. Use this to customize the image: "
+            "edit, then `aetherion --build-image --build-dir PATH`."
+        ),
+    )
+    parser.add_argument(
+        "-e", "--env",
+        action="append",
+        default=[],
+        metavar="NAME=VALUE",
+        help=(
+            "Set an environment variable inside the container. Repeat for "
+            "multiple (e.g. -e ONE=1 --env TWO=2). Values may contain spaces "
+            "if quoted at the shell: --env 'NAME=has spaces'. A bare name "
+            "with no `=` inherits the value from the host environment."
+        ),
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    # argv=None lets the console-script entry point (pyproject.toml) call
+    # main() with no args while keeping the parameter explicit for tests
+    # and for the `python -m aetherion` wrapper.
+    if argv is None:
+        argv = sys.argv[1:]
+    args = _parse_args(argv)
+
+    # --extract is terminal: it never launches the container.
+    if args.extract is not None:
+        return _extract_bundle(Path(args.extract).expanduser().resolve())
+
+    unknown = [a for a in args.agents if a not in AGENT_PATHS]
+    if unknown:
+        sys.stderr.write(
+            f"aetherion: unknown agent(s): {', '.join(unknown)}\n"
+            f"aetherion: known agents: {', '.join(AGENT_PATHS)}\n"
+        )
+        return 2
+
+    selected: list[str] = args.agents
+    if set(selected) != set(AGENT_PATHS):
+        scope = ", ".join(selected) if selected else "(none)"
+        sys.stderr.write(f"aetherion: agent scope limited to: {scope}\n")
+
+    image: str = args.image
+
+    # --build-image is terminal: it never launches the container, regardless
+    # of build success or failure. The build's exit code propagates as-is.
+    if args.build_image:
+        context = (
+            Path(args.build_dir).expanduser().resolve()
+            if args.build_dir is not None
+            else _bundled_assets_dir()
+        )
+        return _build_image(image, context)
+
+    if not _image_exists(image):
+        sys.stderr.write(
+            f"aetherion: image '{image}' is not present locally.\n"
+            "aetherion: this launcher does not pull images — build it locally:\n"
+            f"  aetherion --build-image"
+            + (f" --image {image}" if image != DEFAULT_IMAGE else "")
+            + "\n"
+            "aetherion: or extract a copy of the build files first to customize:\n"
+            "  aetherion --extract <path>\n"
+        )
+        return 1
+
+    home = Path.home()
+    pwd = Path.cwd()
+
+    data_dir = home / ".aetherion" / "data"
+    data_dir.mkdir(parents=True, exist_ok=True)
+
+    # Rewrite host home → container home so a host path of ~/foo lands at ~/foo
+    # inside the container too. Anything outside $HOME is mounted at its real
+    # path, since there's no portable home-relative form for it.
+    if pwd == home:
+        container_workdir = CONTAINER_HOME
+    elif home in pwd.parents:
+        container_workdir = f"{CONTAINER_HOME}/{pwd.relative_to(home)}"
+    else:
+        container_workdir = str(pwd)
+
+    mounts: list[str] = []
+    # (agent, rel) for each deferred path so the first-run notice and the
+    # post-exit "preserved <agent>" log can name the agent that owns it.
+    deferred: list[tuple[str, str]] = []
+
+    for agent in selected:
+        for rel in AGENT_PATHS[agent]:
+            host_path = data_dir / rel
+            container_path = f"{CONTAINER_HOME}/{rel}"
+            if host_path.exists():
+                mounts += ["-v", f"{host_path}:{container_path}:z"]
+            else:
+                deferred.append((agent, rel))
+
+    if deferred:
+        sys.stderr.write(
+            "aetherion: these agent paths are not yet preserved on the host;\n"
+            "any that get created during the session will be extracted on clean exit:\n"
+        )
+        last_agent: str | None = None
+        for agent, rel in deferred:
+            if agent != last_agent:
+                sys.stderr.write(f"  [{agent}]\n")
+                last_agent = agent
+            sys.stderr.write(f"    - {data_dir / rel}\n")
+        sys.stderr.write("aetherion: let the container exit cleanly, do not SIGKILL the launcher.\n\n")
+
+    # --cidfile instead of --rm: we need the container to outlive the shell so
+    # we can diff and `cp` config out before removing it.
+    instance_id = secrets.token_hex(4)
+    instance_name = f"aetherion-{instance_id}"
+
+    with tempfile.TemporaryDirectory(prefix="aetherion-cid-") as td:
+        cidfile = Path(td) / "cid"
+
+        # Passed through subprocess as separate argv entries, so values with
+        # spaces or shell-special characters are safe — no shell evaluation.
+        env_args: list[str] = []
+        for kv in args.env:
+            env_args += ["-e", kv]
+
+        run_argv = [
+            CONTAINER_RUNTIME, "run",
+            *user_ns_args(),
+            "--name", instance_name,
+            "--hostname", instance_id,
+            "--cidfile", str(cidfile),
+            *env_args,
+            "-v", f"{pwd}:{container_workdir}:z",
+            "-w", container_workdir,
+            *mounts,
+            "-it",
+            image,
+        ]
+
+        rc = subprocess.run(run_argv).returncode
+
+        if not cidfile.exists():
+            return rc
+
+        cid = cidfile.read_text().strip()
+
+        try:
+            if deferred:
+                preserve_agent_state(cid, deferred, data_dir)
+        finally:
+            subprocess.run(
+                [CONTAINER_RUNTIME, "rm", "-f", cid],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+
+    return rc
+
+
+def _image_exists(image: str) -> bool:
+    return subprocess.run(
+        [CONTAINER_RUNTIME, "image", "inspect", image],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    ).returncode == 0
+
+
+def _build_image(image: str, context: Path) -> int:
+    if not context.is_dir():
+        sys.stderr.write(f"aetherion: build context does not exist: {context}\n")
+        return 1
+    if not (context / "Dockerfile").is_file():
+        sys.stderr.write(
+            f"aetherion: no Dockerfile found in build context: {context}\n"
+            "aetherion: run `aetherion --extract <path>` to populate one.\n"
+        )
+        return 1
+    sys.stderr.write(f"aetherion: building {image} from {context}\n")
+    return subprocess.run(
+        [CONTAINER_RUNTIME, "build", "-t", image, str(context)],
+    ).returncode
+
+
+def _extract_bundle(dest: Path) -> int:
+    src = _bundled_assets_dir()
+    missing = [name for name in BUNDLED_ASSETS if not (src / name).exists()]
+    if missing:
+        sys.stderr.write(
+            f"aetherion: bundled asset(s) missing from {src}: {', '.join(missing)}\n"
+            "aetherion: this launcher must be run from a complete source tree.\n"
+        )
+        return 1
+
+    dest.mkdir(parents=True, exist_ok=True)
+    for name in BUNDLED_ASSETS:
+        s = src / name
+        d = dest / name
+        if s.is_dir():
+            # dirs_exist_ok overlays into an existing tree rather than failing,
+            # but it still only touches files that exist in the source — so any
+            # extra files the user added under dest/<name>/ stay put.
+            shutil.copytree(s, d, dirs_exist_ok=True)
+        else:
+            shutil.copy2(s, d)
+
+    sys.stderr.write(
+        f"aetherion: extracted {', '.join(BUNDLED_ASSETS)} to {dest}\n"
+        f"aetherion: build with: aetherion --build-image --build-dir {dest}\n"
+    )
+    return 0
+
+
+def preserve_agent_state(cid: str, deferred: list[tuple[str, str]], data_dir: Path) -> None:
+    # Use `<runtime> diff` to find which deferred paths the container actually
+    # touched. Skipping `cp` on untouched paths avoids spurious errors and
+    # keeps the host clean of empty agent dirs from sessions where the user
+    # never logged in.
+    touched = _diff_paths(cid)
+    for agent, rel in deferred:
+        container_path = f"{CONTAINER_HOME}/{rel}"
+        if not _was_touched(container_path, touched):
+            continue
+        host_path = data_dir / rel
+        if extract(cid, container_path, host_path):
+            sys.stderr.write(f"aetherion: preserved {agent} state at {host_path}\n")
+
+
+def _diff_paths(cid: str) -> set[str]:
+    """Return the set of container-fs paths reported as Added or Changed by
+    `<runtime> diff`. Deletes are ignored — nothing to extract."""
+    result = subprocess.run(
+        [CONTAINER_RUNTIME, "diff", cid],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return set()
+    paths: set[str] = set()
+    for line in result.stdout.splitlines():
+        kind, _, path = line.partition(" ")
+        if kind in ("A", "C") and path:
+            paths.add(path)
+    return paths
+
+
+def _was_touched(target: str, touched: set[str]) -> bool:
+    if target in touched:
+        return True
+    prefix = target + "/"
+    return any(p.startswith(prefix) for p in touched)
+
+
+def extract(cid: str, src_in_container: str, dst_on_host: Path) -> bool:
+    dst_on_host.parent.mkdir(parents=True, exist_ok=True)
+
+    # Stage to a sibling tmp path so the final move into place is an atomic
+    # rename on the same filesystem — no half-written config visible to a
+    # future run.
+    staging = dst_on_host.with_name(dst_on_host.name + ".tmp-extract")
+    _remove(staging)
+
+    cp = subprocess.run(
+        [CONTAINER_RUNTIME, "cp", f"{cid}:{src_in_container}", str(staging)],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+    )
+
+    if cp.returncode != 0:
+        _remove(staging)
+        return False
+
+    # Defensive: dst shouldn't exist (deferred = not on host at launch), but
+    # if a concurrent run raced us, clear it so os.replace can land cleanly
+    # even when staging is a directory.
+    _remove(dst_on_host)
+    os.replace(staging, dst_on_host)
+    return True
+
+
+def _remove(path: Path) -> None:
+    if path.is_dir() and not path.is_symlink():
+        shutil.rmtree(path)
+    elif path.exists() or path.is_symlink():
+        path.unlink()
+
+
+if __name__ == "__main__":
+    sys.exit(main())