Add distant-docker backend plugin for Docker container interaction

Implements a full distant Api backend that communicates with Docker
containers via the Bollard API. Supports both Unix (Linux) and Windows
(nanoserver) containers through DockerFamily-based dispatch.

Key features:
- File I/O via Docker tar archive API (no shell required)
- Process spawning with simple and PTY modes
- Shell command dispatch (sh -c / cmd /c) based on container OS
- Search support: rg/grep/find on Unix, findstr on Windows
- Windows drive-letter path parsing in search output
- Integration tests covering file ops, dirs, search, metadata, and processes

Author: chipsenkbeil

.config/nextest.toml

@@ -1,6 +1,9 @@
 [test-groups.ssh-integration]
 max-threads = 4
 
+[test-groups.docker-integration]
+max-threads = 2
+
 [profile.ci]
 fail-fast = false
 retries = 4
@@ -11,3 +14,7 @@ final-status-level = "fail"
 [[profile.ci.overrides]]
 filter = 'binary_id(distant-ssh::lib)'
 test-group = 'ssh-integration'
+
+[[profile.ci.overrides]]
+filter = 'binary_id(distant-docker::lib)'
+test-group = 'docker-integration'

.github/workflows/ci.yml

@@ -128,6 +128,12 @@ jobs:
       - name: Ensure /run/sshd exists on Unix
         run: sudo mkdir -p /run/sshd
         if: matrix.os == 'ubuntu-latest'
+      - name: Pre-pull Docker test image (Linux)
+        run: docker pull ubuntu:22.04
+        if: matrix.os == 'ubuntu-latest'
+      - name: Pre-pull Docker test image (Windows)
+        run: docker pull mcr.microsoft.com/windows/nanoserver:ltsc2025
+        if: matrix.os == 'windows-latest'
       - name: Run all workspace tests (all features)
         run: cargo nextest run --profile ci --release --all-features --workspace
       - name: Run all doc tests (all features)

AGENTS.md

@@ -8,21 +8,24 @@ manipulation.
 ## Project Overview
 
 - **Language:** Rust (Edition 2024, MSRV 1.88.0)
-- **Architecture:** Cargo workspace with 4 member crates
+- **Architecture:** Cargo workspace with 5 member crates
 - **Project Type:** CLI application with client-server architecture
 - **Main Crates:**
   - `distant` - Main binary implementation providing commands like `distant
     api`, `distant connect`, and `distant launch`
   - `distant-core` - Core library with API, protocol, plugin trait, and
     utilities
+  - `distant-docker` - Docker backend plugin using the Bollard API to interact
+    with containers; supports both Unix and Windows (`nanoserver`) containers
+    via `DockerFamily` dispatch
   - `distant-host` - Custom server implementation to run on a host machine that
     implements the full distant specification, also providing a client-side
     plugin
   - `distant-ssh` - pure Rust SSH client-side plugin compatible with distant
     specification
   - `distant-test-harness` - non-published crate that provides test utilities to
     run e2e system tests that involve standing up distant servers, managers,
-    sshd, and more
+    sshd, Docker containers, and more
 
 ## General AI Workflow
 
@@ -55,8 +58,9 @@ To move beyond basic code generation, use the following patterns:
    on what has changed.
     1. **All tests:** `cargo test --all-features --workspace`
     2. **Core tests:** `cargo test --all-features -p distant-core`
-    2. **Host tests:** `cargo test --all-features -p distant-host`
-    2. **SSH tests:** `cargo test --all-features -p distant-ssh`
+    3. **Docker tests:** `cargo test --all-features -p distant-docker`
+    4. **Host tests:** `cargo test --all-features -p distant-host`
+    5. **SSH tests:** `cargo test --all-features -p distant-ssh`
 
 ## Memory Bank Maintenance (`CLAUDE.md` aka `AGENTS.md`)
 
@@ -88,6 +92,16 @@ later to resolve will be placed here.
    may be incomplete/untested.
 2. Windows CI SSH tests have intermittent auth failures from resource
    contention — mitigated with nextest retries (4x), not root-caused.
+3. `distant-docker` search on Windows containers uses `findstr.exe` which has
+   limited regex support (no `+`, `?`, `|`, `{n,m}`). `Regex` and `Or` query
+   conditions return `Unsupported` on Windows — only `Contains`, `Equals`,
+   `StartsWith`, and `EndsWith` are supported.
+4. `distant-docker` `append_file` on Windows falls back to tar read-modify-write
+   because there's no good stdin-append equivalent to `cat >>` on nanoserver.
+5. Nanoserver `ContainerUser` cannot write to `C:\Windows\Temp` or other system
+   directories via exec commands (`mkdir`, `move`, etc.). The Docker tar API
+   bypasses permissions but exec-based operations require a user-writable
+   directory. Tests use `C:\temp` (pre-created via tar API in the test harness).
 
 ## Tooling & Command Reference
 
@@ -105,6 +119,7 @@ cargo build --all-features --workspace
 
 # Build specific crates
 cargo build -p distant-core
+cargo build -p distant-docker
 cargo build -p distant-host
 cargo build -p distant-ssh
 ```
@@ -191,6 +206,43 @@ Keep a list of patterns to **avoid**:
 4. Don't run mass parallel SSH integration tests without throttling — use
    nextest `test-groups` with `max-threads` (configured in
    `.config/nextest.toml`).
+5. Always create a **feature branch** before starting multi-file or multi-phase
+   work — never commit directly to `master`. Use
+   `git checkout -b feature/<name>` before writing any code.
+6. **Commit per-phase** (or at minimum per logical unit of work) — don't
+   accumulate an entire feature as uncommitted changes across many phases. Each
+   phase should be a separate commit with `cargo fmt` and `cargo clippy` passing
+   before the commit is created.
+7. Always **run tests** (`cargo test --all-features -p <crate>`) after creating
+   or modifying test files — don't assume tests compile or pass without actually
+   executing them.
+8. Don't hardcode `sh -c` for shell commands in `distant-docker` — Windows
+   containers (nanoserver) don't have `sh`. Use the `run_shell_cmd` /
+   `run_shell_cmd_stdout` helpers which dispatch to `sh -c` or `cmd /c` based
+   on `DockerFamily`.
+9. Don't hardcode Unix paths like `/tmp` in Docker tests — use `test_temp_dir()`
+   which returns `/tmp` on Unix and `C:\temp` on Windows. Don't use
+   `C:\Windows\Temp` — `ContainerUser` cannot write there.
+10. Don't double-wrap Windows commands with `cmd /c` — when using
+    `run_shell_cmd` the shell prefix is already provided, so command strings
+    should contain only the inner command (e.g. `mkdir "path"` not
+    `cmd /c mkdir "path"`).
+11. Don't use forward-slash separators inside `PathBuf::join()` for
+    multi-component paths — `join("a/b/c")` embeds a Unix separator and
+    can break on Windows. Use chained `.join("a").join("b").join("c")`.
+12. When writing Docker tests (commands, paths, filenames), always consider
+    Windows container compatibility — use `test_temp_dir()` for temp paths,
+    chain `.join()` calls for path components, and use `cfg!(windows)` for
+    any platform-specific commands or assertions.
+13. Never bypass GPG commit signing — don't use `-c commit.gpgsign=false`
+    or `--no-gpg-sign`. If `gpg failed to sign the data`, stop and let the
+    user resolve the signing issue. The user's GPG key also handles SSH
+    push authentication.
+14. Never dismiss test failures as "intermittent" or "pre-existing" without
+    investigation. Every failure — even if it only reproduces sometimes —
+    must be analyzed to determine the root cause and a recommendation given
+    to fix it. If the root cause is a bug in production code, focus the
+    recommendation on the production code fix, not on test workarounds.
 
 ### Format standards