dockhand-cli 0.3.1__py3-none-any.whl

dockhand/submit.py

@@ -0,0 +1,163 @@
+"""Docker container submission and queuing."""
+from typing import List
+
+import typer
+from git import InvalidGitRepositoryError, Repo
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from dockhand.client import get_client
+from dockhand.config import DockerConfig, cli_config
+from dockhand.history import add_to_history
+from dockhand.sync import execute_sync
+
+
+def _build_docker_run_cmd(
+    config: DockerConfig,
+    commands: List[str],
+    imagename: str,
+    gpus: str | None,
+    effective_ports: list[str] | None,
+    mount_code: bool = True,
+    run_flags: list[str] | None = None,
+) -> str:
+    """Build the docker run command string.
+
+    When ``mount_code`` is True (mount delivery) the project directory is bind-mounted
+    over ``containerworkdir`` and ``preserve_paths`` anonymous volumes are layered on
+    top. When False (bake delivery) the code is already baked into ``imagename``, so no
+    code mount or preserve volumes are emitted — only data volumes.
+    """
+    code_mounts = []
+    if mount_code:
+        if config.containerworkdir == "/":
+            typer.echo(
+                "Warning: containerworkdir is '/' — mounting code at the container root "
+                "will shadow the entire filesystem.",
+                err=True,
+            )
+        # Implicit code mount: remote project path → containerworkdir
+        code_mounts.append(f"-v {cli_config.remote_path}:{config.containerworkdir}:rw")
+
+        # Anonymous volumes layered on top of the code mount for paths that must keep the
+        # image's build-time contents (e.g. a virtualenv or node_modules baked in at build
+        # time) instead of being shadowed by the bind-mounted host project directory.
+        workdir = config.containerworkdir.rstrip("/")
+        code_mounts += [f"-v {workdir}/{path.strip('/')}" for path in config.preserve_paths]
+
+    data_volumes = []
+    if config.volumes is not None:
+        data_volumes = [f"-v {v['hostpath']}:{v['containerpath']}:{v['permissions']}" for v in config.volumes]
+
+    gpu_flags = [f"--gpus {gpus}"] if gpus is not None else []
+    port_flags = [f"-p {mapping}" for mapping in effective_ports] if effective_ports is not None else []
+
+    # Run flags come from the transport (e.g. ["--rm"] for the queue, or
+    # ["-d", "--name", ...] for a detached direct run).
+    run_flags = ["--rm"] if run_flags is None else run_flags
+
+    return " ".join(
+        [
+            "docker",
+            "run",
+            *run_flags,
+            *code_mounts,
+            *data_volumes,
+            *gpu_flags,
+            *port_flags,
+            imagename,
+            *commands,
+        ]
+    )
+
+
+def _get_branch() -> str | None:
+    try:
+        with Repo(cli_config.project_root) as repo:
+            return repo.active_branch.name
+    except (InvalidGitRepositoryError, Exception):
+        return None
+
+
+def execute_submit(
+    config: DockerConfig,
+    commands: List[str],
+    sync: bool,
+    imagename: str | None = None,
+    gpus: str | None = None,
+    ports: list[str] | None = None,
+    urgent: bool = False,
+    slots: int | None = None,
+    image_ref: str | None = None,
+) -> int:
+    """Optionally sync code, then start a container run. Returns the local job ID.
+
+    Runs through the queue (task spooler) when ``queue.enabled``, otherwise starts a
+    detached container directly. When ``image_ref`` is given (e.g. resubmitting a baked
+    job), that exact pre-built image is run verbatim — no re-resolution and no rebuild.
+    """
+    from dockhand.build import execute_build
+    from dockhand.history import reserve_local_id
+    from dockhand.tagging import resolve_image_ref
+    from dockhand.transport import get_transport
+
+    if sync:
+        execute_sync(confirm_changes=True)
+
+    imagename = imagename or config.imagename
+    gpus = gpus if gpus is not None else config.gpus
+    effective_ports = ports if ports is not None else config.ports
+    effective_slots = slots if slots is not None else cli_config.queue.slots
+
+    transport = get_transport()
+    local_id = reserve_local_id()
+
+    if image_ref is not None:
+        # Rerun an exact pre-built image (baked); no re-resolution, no rebuild.
+        run_image = image_ref
+        mount_code = False
+    else:
+        delivery = config.resolve_code_delivery(cli_config.queue.enabled)
+        if delivery == "bake":
+            # Bake the code into an image and run that; no code mount at run time. Queued
+            # jobs get an immutable per-submit tag so they stay pinned to their code.
+            run_image = resolve_image_ref(imagename, unique=cli_config.queue.enabled)
+            execute_build(config, sync=False, dockerfile=config.dockerfile, imagename=run_image)
+            mount_code = False
+        else:
+            run_image = imagename
+            mount_code = True
+
+    docker_cmd = _build_docker_run_cmd(
+        config,
+        commands,
+        run_image,
+        gpus,
+        effective_ports,
+        mount_code=mount_code,
+        run_flags=transport.run_flags(local_id),
+    )
+
+    with get_client() as client:
+        with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}")) as progress:
+            task = progress.add_task(description="Submitting job", total=None)
+            handle = transport.submit(
+                client, docker_cmd, local_id=local_id, slots=effective_slots, urgent=urgent
+            )
+            progress.update(task, completed=True)
+
+    host = cli_config.ssh.hostname if cli_config.ssh else "localhost"
+    add_to_history(
+        config,
+        commands=commands,
+        local_id=local_id,
+        handle=handle,
+        image_ref=run_image,
+        branch=_get_branch(),
+        ports=effective_ports,
+        host=host,
+    )
+
+    verb = "Queued" if cli_config.queue.enabled else "Started"
+    label = "urgent job" if (urgent and cli_config.queue.enabled) else "job"
+    typer.echo(f"{verb} {label} #{local_id}")
+    return local_id

dockhand/sync.py

@@ -0,0 +1,50 @@
+import subprocess
+
+import typer
+from git import Repo
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.prompt import Confirm
+
+from dockhand.config import cli_config
+from dockhand.error import error_and_exit
+
+
+def execute_sync(confirm_changes: bool = True):
+    if confirm_changes:
+        check_and_confirm_changes()
+
+    ssh = cli_config.ssh
+    source = "./"
+    destination = f"{ssh.user}@{ssh.hostname}:{cli_config.remote_path}"
+    command = [
+        "rsync",
+        "-avz",
+        "-e",
+        f"ssh -i {ssh.identityfile}",
+        "--exclude-from=.gitignore",
+        "--delete",
+        source,
+        destination,
+    ]
+
+    with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}")) as progress:
+        task = progress.add_task(description="Syncing", total=None)
+        progress.start()
+        try:
+            subprocess.run(command, check=True, capture_output=True)
+        except subprocess.CalledProcessError as e:
+            error_and_exit(f"Sync failed:\n{e.stderr.decode()}")
+        progress.update(task, completed=True)
+
+
+def check_and_confirm_changes():
+    with Repo(cli_config.project_root) as repo:
+        if repo.is_dirty() or len(repo.untracked_files) != 0:
+            prompt = (
+                "You have uncommitted changes.\n"
+                + "This may cause problems with switching branches.\n"
+                + "Do you want to continue synchronizing?"
+            )
+            confirmed = Confirm.ask(prompt, show_default=True, default=True)
+            if not confirmed:
+                raise typer.Exit()

dockhand/tagging.py

@@ -0,0 +1,48 @@
+"""Image tag resolution for baked code delivery."""
+import hashlib
+import time
+
+from git import Repo
+
+from dockhand.config import cli_config
+
+
+def resolve_image_ref(imagename: str, unique: bool) -> str:
+    """Return the image ref to build and run for baked code delivery.
+
+    ``unique=True`` (queued jobs) produces an immutable, content-addressed tag so a
+    job waiting in the queue is pinned to the exact code it was submitted with, and
+    a later submit cannot retroactively change it. ``unique=False`` (immediate,
+    unqueued run) reuses a single tag since there is no drift window to guard against.
+    """
+    if not unique:
+        return imagename  # implicit :latest, rebuilt on each submit
+    return f"{imagename}:{_content_tag()}"
+
+
+def _content_tag() -> str:
+    """Derive a tag from the project's git state.
+
+    A clean worktree maps to its commit sha (fully reproducible). A dirty worktree
+    folds tracked changes and untracked filenames into the tag so distinct working
+    states get distinct images while identical states dedupe. Note that untracked
+    file *contents* are not hashed — commit before queued submits for a guaranteed
+    immutable snapshot. Falls back to a time-based tag outside a git repo.
+    """
+    try:
+        repo = Repo(cli_config.project_root)
+        sha = repo.head.commit.hexsha[:12]
+        dirty = repo.is_dirty(untracked_files=True)
+        diff = repo.git.diff() if dirty else ""
+        untracked = sorted(repo.untracked_files) if dirty else []
+    except Exception:
+        return f"ts-{int(time.time())}"
+
+    if not dirty:
+        return sha
+
+    h = hashlib.sha256()
+    h.update(diff.encode())
+    for path in untracked:
+        h.update(path.encode())
+    return f"{sha}-dirty-{h.hexdigest()[:8]}"

dockhand/transport.py

@@ -0,0 +1,212 @@
+"""Execution transports: task-spooler queue vs. direct ``docker run``.
+
+When ``queue.enabled`` is true, jobs are submitted to task spooler (``tsp``) and run
+in submission order. When it is false there is no queue, so jobs are started
+immediately as detached containers (``docker run -d``) and managed directly with
+``docker logs``/``stop``/``ps``/``rm``.
+
+Both backends expose the same interface so ``submit`` and the management commands
+(``logs``/``stop``/``jobs``/``remove``) don't care which is active. A job's transport
+is recorded in history, so per-job commands dispatch to the backend that created it.
+"""
+from abc import ABC, abstractmethod
+
+import typer
+
+from dockhand.client.base import Client
+from dockhand.config import cli_config
+from dockhand.error import error_and_exit
+from dockhand.queue import ts_get_job, ts_kill, ts_list, ts_make_urgent, ts_remove, ts_submit
+
+
+def _container_name(local_id: int) -> str:
+    return f"dockhand-{local_id}"
+
+
+def get_transport() -> "Transport":
+    """Select the transport for a new submission based on ``queue.enabled``."""
+    return TaskSpoolerTransport() if cli_config.queue.enabled else DockerTransport()
+
+
+def transport_for_entry(entry: dict) -> "Transport":
+    """Select the transport that created an existing history entry.
+
+    Old entries predate the ``transport`` field and were always task spooler.
+    """
+    name = entry.get("transport", TaskSpoolerTransport.name)
+    return _TRANSPORTS.get(name, TaskSpoolerTransport())
+
+
+def entry_handle(entry: dict):
+    """The backend handle for an entry (tsp job id, or container name)."""
+    return entry.get("handle", entry.get("ts_job_id"))
+
+
+class Transport(ABC):
+    name: str
+
+    @abstractmethod
+    def run_flags(self, local_id: int) -> list[str]:
+        """Flags injected right after ``docker run`` (e.g. ``--rm`` or ``-d --name``)."""
+
+    @abstractmethod
+    def submit(self, client: Client, docker_cmd: str, *, local_id: int, slots: int, urgent: bool) -> dict:
+        """Start the job. Returns a handle dict merged into the history entry."""
+
+    @abstractmethod
+    def list_jobs(self, client: Client) -> list[dict]:
+        """Live jobs as dicts: ``{handle, state, command}`` (states normalized)."""
+
+    @abstractmethod
+    def container_name(self, entry: dict) -> str | None:
+        """The docker container name backing this job, for ``docker inspect`` (e.g. exact
+        start time). None if the job predates deterministic container naming."""
+
+    @abstractmethod
+    def logs(self, client: Client, entry: dict, *, n: int | None, follow: bool) -> int:
+        """Stream a job's logs. Returns the command's exit code."""
+
+    @abstractmethod
+    def stop(self, client: Client, entry: dict) -> bool:
+        """Stop a running job."""
+
+    @abstractmethod
+    def remove(self, client: Client, entry: dict) -> bool:
+        """Remove a job that hasn't started (queued) / clean up its container."""
+
+
+class TaskSpoolerTransport(Transport):
+    name = "task_spooler"
+
+    def run_flags(self, local_id: int) -> list[str]:
+        # Named (as well as --rm) so a running job's container can still be inspected for
+        # its exact start time — ts itself doesn't expose one.
+        return ["--rm", "--name", _container_name(local_id)]
+
+    def submit(self, client, docker_cmd, *, local_id, slots, urgent):
+        job_id = ts_submit(client, docker_cmd, cwd=cli_config.remote_path, slots=slots)
+        if urgent:
+            ts_make_urgent(client, job_id, cwd=cli_config.remote_path)
+        return {"transport": self.name, "handle": job_id, "ts_job_id": job_id}
+
+    def list_jobs(self, client):
+        jobs = ts_list(client, cwd=cli_config.remote_path)
+        return [
+            {
+                "handle": j["id"],
+                "state": j["state"],
+                "command": j["command"],
+                "duration_seconds": j.get("duration_seconds"),
+            }
+            for j in jobs
+        ]
+
+    def container_name(self, entry):
+        local_id = entry.get("local_id")
+        # Only jobs submitted after this transport started naming containers have one.
+        return _container_name(local_id) if local_id is not None else None
+
+    def logs(self, client, entry, *, n, follow):
+        job_id = entry_handle(entry)
+        if follow:
+            cmd = f"tail -f $(tsp -o {job_id})"
+        elif n is not None:
+            cmd = f"tail -n {n} $(tsp -o {job_id})"
+        else:
+            cmd = f"cat $(tsp -o {job_id})"
+        returncode, _ = client.run(cmd, cwd=cli_config.remote_path)
+        return returncode
+
+    def stop(self, client, entry):
+        job_id = entry_handle(entry)
+        job = ts_get_job(client, job_id, cwd=cli_config.remote_path)
+        if job is None:
+            error_and_exit(f"Job (tsp {job_id}) not found in task spooler.")
+        if job["state"] != "running":
+            error_and_exit(f"Job is not running (state: {job['state']}). Use 'remove' for queued jobs.")
+        return ts_kill(client, job_id, cwd=cli_config.remote_path)
+
+    def remove(self, client, entry):
+        job_id = entry_handle(entry)
+        job = ts_get_job(client, job_id, cwd=cli_config.remote_path)
+        if job and job["state"] != "queued":
+            error_and_exit(f"Job is not queued (state: {job['state']}). Use 'stop' to terminate running jobs.")
+        return ts_remove(client, job_id, cwd=cli_config.remote_path)
+
+
+# docker container State → the queue-style state labels the UI already knows.
+_DOCKER_STATE_MAP = {
+    "running": "running",
+    "created": "queued",
+    "restarting": "running",
+    "paused": "running",
+    "exited": "finished",
+    "dead": "failed",
+    "removing": "finished",
+}
+
+
+class DockerTransport(Transport):
+    name = "docker"
+
+    def run_flags(self, local_id: int) -> list[str]:
+        # Detached, named, and NOT --rm so logs survive after the container exits.
+        return ["-d", "--name", _container_name(local_id)]
+
+    def submit(self, client, docker_cmd, *, local_id, slots, urgent):
+        if urgent:
+            typer.echo("Warning: --urgent has no effect without a queue.", err=True)
+        returncode, _ = client.run(docker_cmd, cwd=cli_config.remote_path, capture=True)
+        if returncode != 0:
+            error_and_exit(f"docker run failed (exit {returncode}).")
+        return {"transport": self.name, "handle": _container_name(local_id)}
+
+    def list_jobs(self, client):
+        fmt = "{{.Names}}\t{{.State}}\t{{.Command}}"
+        returncode, stdout = client.run(
+            f"docker ps -a --filter name=dockhand- --format '{fmt}'", cwd=cli_config.remote_path, capture=True
+        )
+        if returncode != 0:
+            return []
+        jobs = []
+        for line in stdout.strip().split("\n"):
+            if not line.strip():
+                continue
+            parts = line.split("\t")
+            if len(parts) < 2:
+                continue
+            name, state = parts[0], parts[1]
+            command = parts[2].strip('"') if len(parts) > 2 else ""
+            jobs.append({"handle": name, "state": _DOCKER_STATE_MAP.get(state, state), "command": command})
+        return jobs
+
+    def container_name(self, entry):
+        return entry_handle(entry)
+
+    def logs(self, client, entry, *, n, follow):
+        name = entry_handle(entry)
+        flags = []
+        if follow:
+            flags.append("-f")
+        if n is not None:
+            flags.append(f"--tail {n}")
+        cmd = f"docker logs {' '.join(flags)} {name}".replace("  ", " ")
+        returncode, _ = client.run(cmd, cwd=cli_config.remote_path)
+        return returncode
+
+    def stop(self, client, entry):
+        name = entry_handle(entry)
+        returncode, _ = client.run(f"docker stop {name}", cwd=cli_config.remote_path, capture=True)
+        return returncode == 0
+
+    def remove(self, client, entry):
+        # No queue to dequeue from — remove the container record (force-remove if running).
+        name = entry_handle(entry)
+        returncode, _ = client.run(f"docker rm -f {name}", cwd=cli_config.remote_path, capture=True)
+        return returncode == 0
+
+
+_TRANSPORTS = {
+    TaskSpoolerTransport.name: TaskSpoolerTransport(),
+    DockerTransport.name: DockerTransport(),
+}

dockhand/tunnel.py

@@ -0,0 +1,62 @@
+"""SSH local port forwarding to docker container ports."""
+import time
+from contextlib import ExitStack
+
+import fabric
+import typer
+
+from dockhand.config import cli_config
+from dockhand.error import error_and_exit
+from dockhand.history import load_history
+
+
+def execute_tunnel(*, container_id: str | None, ports: list[str] | None):
+    """Forward ports to localhost via SSH tunnel.
+
+    If ports are provided, use those. Otherwise read from the last (or specified) history entry.
+    """
+    # Resolve port list: explicit override takes priority over history
+    if ports:
+        effective_ports = ports
+    else:
+        history = load_history()
+        if not history:
+            error_and_exit("No container history found. Run a container first.")
+
+        if container_id is not None:
+            entry = next((e for e in history if e["container_id"] == container_id), None)
+            if entry is None:
+                error_and_exit(f"Container ID '{container_id}' not found in history.")
+        else:
+            entry = history[-1]
+
+        effective_ports = entry["config"].get("ports") or []
+        if not effective_ports:
+            error_and_exit("No port mappings in history. Use -p to specify ports explicitly.")
+
+    # Parse "hostPort:containerPort" → forward local hostPort to remote hostPort
+    host_ports = []
+    for mapping in effective_ports:
+        parts = mapping.split(":")
+        if len(parts) != 2:
+            error_and_exit(f"Unexpected port mapping format: '{mapping}'. Expected 'hostPort:containerPort'.")
+        host_ports.append(int(parts[0]))
+
+    ssh = cli_config.ssh
+    conn = fabric.Connection(
+        host=ssh.hostname,
+        user=ssh.user,
+        connect_kwargs={"key_filename": ssh.identityfile},
+    )
+
+    typer.echo(f"Forwarding ports: {', '.join(str(p) for p in host_ports)}")
+    typer.echo("Press Ctrl+C to stop the tunnel.")
+
+    with ExitStack() as stack:
+        for port in host_ports:
+            stack.enter_context(conn.forward_local(port, remote_host="localhost", remote_port=port))
+        try:
+            while True:
+                time.sleep(1)
+        except KeyboardInterrupt:
+            typer.echo("\nTunnel closed.")

dockhand/volumes.py

@@ -0,0 +1,149 @@
+"""Docker volume inspection and path resolution."""
+
+from rich.console import Console
+from rich.tree import Tree
+
+from dockhand.client import get_client
+from dockhand.config import DockerConfig, cli_config
+
+# Default scan depth when --depth is not specified.
+# Keeps the find command fast on large volumes; use --depth N to go deeper.
+DEFAULT_SCAN_DEPTH = 5
+
+# Directories pruned from every find scan.
+_PRUNE_DIRS = {".git", "__pycache__", ".venv", "venv", "node_modules", ".mypy_cache", ".ruff_cache", ".pytest_cache"}
+_PRUNE_EXPR = " -o ".join(f"-name {d}" for d in sorted(_PRUNE_DIRS))
+
+
+def _workdir_relative(containerpath: str, workdir: str) -> str:
+    """Convert an absolute container path to a workdir-relative path."""
+    workdir = workdir.rstrip("/")
+    containerpath = containerpath.rstrip("/")
+    if containerpath.startswith(workdir + "/"):
+        return containerpath[len(workdir) + 1 :]
+    if containerpath == workdir:
+        return "."
+    return containerpath
+
+
+def _resolve_to_host(relative_path: str, config: DockerConfig) -> tuple[str, str] | None:
+    """Map a workdir-relative path to the host path where it lives.
+
+    Checks data volumes first (most specific match wins), then falls back to
+    the code mount (project root → containerworkdir).
+    """
+    workdir = config.containerworkdir.rstrip("/")
+    for volume in config.volumes or []:
+        containerpath = volume["containerpath"].rstrip("/")
+        hostpath = volume["hostpath"].rstrip("/")
+        vol_relative = _workdir_relative(containerpath, workdir)
+        if vol_relative == ".":
+            # Volume is mounted at workdir itself — matches any relative path.
+            return hostpath + "/" + relative_path, hostpath
+        if relative_path.startswith(vol_relative + "/") or relative_path == vol_relative:
+            suffix = relative_path[len(vol_relative) :]
+            return hostpath + suffix, hostpath
+    # Fall back to the code mount (project root → containerworkdir).
+    if cli_config.remote_path:
+        return cli_config.remote_path.rstrip("/") + "/" + relative_path, cli_config.remote_path
+    return None
+
+
+def _build_tree(paths: list[str], strip_prefix: str) -> dict:
+    """Convert a flat list of absolute paths into a nested dict.
+
+    Each key is a path component; files map to an empty dict,
+    directories to a non-empty dict of their children.
+    """
+    root: dict = {}
+    prefix = strip_prefix.rstrip("/")
+    for path in paths:
+        path = path.strip()
+        if not path:
+            continue
+        if path.startswith(prefix + "/"):
+            relative = path[len(prefix) + 1 :]
+        elif path == prefix:
+            continue
+        else:
+            relative = path
+        node = root
+        for part in relative.split("/"):
+            if part:
+                node = node.setdefault(part, {})
+    return root
+
+
+def _dict_to_rich_tree(d: dict, tree: Tree, remaining_depth: int | None = None) -> None:
+    """Recursively populate a rich Tree from a nested dict.
+
+    Directories (non-empty children) are listed before files, sorted alphabetically.
+    remaining_depth: how many more directory levels to expand fully; None = unlimited.
+    Directories at the limit are shown with a '...' child to signal truncated content.
+    """
+    dirs = {k: v for k, v in d.items() if v}
+    files = {k: v for k, v in d.items() if not v}
+    for name in sorted(dirs):
+        branch = tree.add(f"[bold blue]{name}/[/bold blue]")
+        if remaining_depth is None:
+            _dict_to_rich_tree(dirs[name], branch, None)
+        elif remaining_depth > 1:
+            _dict_to_rich_tree(dirs[name], branch, remaining_depth - 1)
+        else:
+            branch.add("[dim]...[/dim]")
+    for name in sorted(files):
+        tree.add(name)
+
+
+def execute_volumes(
+    config: DockerConfig,
+    depth: int | None = None,
+    imagename: str | None = None,
+    volumes: list | None = None,
+) -> None:
+    """List volume files as they appear inside the container, rooted at containerworkdir."""
+    volumes = volumes if volumes is not None else (config.volumes or [])
+    workdir = (config.containerworkdir or "/").rstrip("/") or "/"
+
+    # Build the full list of mounts: code mount first, then data volumes.
+    # The code mount maps the local project root to containerworkdir, exactly as submit does.
+    mounts: list[dict] = []
+    if cli_config.remote_path:
+        mounts.append({"hostpath": cli_config.remote_path, "containerpath": workdir})
+    mounts.extend(volumes)
+
+    # Scan depth for find: depth+1 ensures folder nodes at the display limit are non-empty.
+    # Without --depth, use DEFAULT_SCAN_DEPTH to keep find fast on large volumes.
+    scan_depth = depth + 1 if depth is not None else DEFAULT_SCAN_DEPTH
+
+    container_paths: list[str] = []
+
+    with get_client() as client:
+        for mount in mounts:
+            hostpath = mount["hostpath"].rstrip("/")
+            containerpath = mount["containerpath"].rstrip("/")
+
+            # cd into hostpath so find outputs relative paths (./a/b/file) — avoids
+            # any prefix-stripping issues caused by tilde expansion or symlinks.
+            # Replace ~ with $HOME so it expands inside bash -l -c "...".
+            hostpath_cmd = hostpath.replace("~", "$HOME")
+            find = f"find . -maxdepth {scan_depth} \\( {_PRUNE_EXPR} \\) -prune -o -type f -print 2>/dev/null"
+            cmd = f"cd {hostpath_cmd} && {find}"
+            exit_code, stdout = client.run(cmd, cwd=None, capture=True)
+
+            if exit_code != 0 or not stdout.strip():
+                continue
+
+            for line in stdout.splitlines():
+                # find . outputs ./relative/path — strip the leading ./
+                rel = line.strip().removeprefix("./")
+                if rel:
+                    container_paths.append(containerpath + "/" + rel)
+
+    tree = Tree(f"[bold]{workdir}[/bold]")
+    if not container_paths:
+        tree.add("[dim](empty or inaccessible)[/dim]")
+    else:
+        _dict_to_rich_tree(_build_tree(container_paths, workdir), tree, remaining_depth=depth)
+
+    Console().print(tree)