Add distant-docker backend plugin for Docker container interaction

Introduce the `distant-docker` crate providing a client-side plugin that
maps the distant API to Docker container operations via the `bollard` crate:

- File operations (read/write/copy/rename/remove) via docker cp and exec
- Directory operations (create/list/remove) via exec
- Process spawn and kill via exec with PTY support
- Search (path/contents) via exec with find/grep
- System info and metadata retrieval via container inspect
- Watching via polling-based exec approach

Additional changes:
- Register DockerPlugin in the manager's launch/connect handlers
- Add docker test harness (distant-test-harness) with container lifecycle
- Configure nextest throttling for docker tests (max-threads = 4)
- Add docker feature flag to CI workflow
- Add workflow anti-patterns to AGENTS.md (feature branches, commit
  per-phase, run tests after writing them)

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,9 @@ 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: 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

@@ -191,6 +191,16 @@ 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.
 
 ### Format standards
 

Cargo.lock

@@ -15,6 +15,7 @@ license = "MIT OR Apache-2.0"
 [workspace]
 members = [
     "distant-core",
+    "distant-docker",
     "distant-host",
     "distant-ssh",
     "distant-test-harness",
@@ -31,6 +32,7 @@ strip = true
 
 [features]
 default = []
+docker = ["dep:distant-docker"]
 
 [dependencies]
 anyhow = "1.0.71"
@@ -65,6 +67,9 @@ which = "4.4.0"
 winsplit = "0.1.0"
 whoami = "1.4.0"
 
+# Optional Docker backend
+distant-docker = { version = "=0.20.0", path = "distant-docker", optional = true }
+
 # Native SSH functionality (always enabled)
 distant-ssh = { version = "=0.20.0", path = "distant-ssh", default-features = false, features = ["serde"] }
 

Cargo.toml

@@ -0,0 +1,43 @@
+[package]
+name = "distant-docker"
+description = "Library to enable Docker container interaction for use with distant sessions"
+categories = ["network-programming"]
+version = "0.20.0"
+authors = ["Chip Senkbeil <chip@senkbeil.org>"]
+edition = "2024"
+homepage = "https://github.com/chipsenkbeil/distant"
+repository = "https://github.com/chipsenkbeil/distant"
+readme = "README.md"
+license = "MIT OR Apache-2.0"
+
+[features]
+default = []
+
+[dependencies]
+async-once-cell = "0.5.2"
+bollard = "0.20"
+bytes = "1"
+derive_more = { version = "0.99.17", default-features = false, features = ["display", "error"] }
+distant-core = { version = "=0.20.0", path = "../distant-core" }
+futures = "0.3.28"
+log = "0.4.18"
+rand = { version = "0.8.5", features = ["getrandom"] }
+semver = "1"
+tar = "0.4"
+tokio = { version = "1.28.2", features = ["full"] }
+
+# Optional serde support for data structures
+serde = { version = "1.0.163", features = ["derive"], optional = true }
+
+[dev-dependencies]
+anyhow = "1.0.71"
+assert_fs = "1.0.13"
+distant-test-harness = { path = "../distant-test-harness", features = ["docker"] }
+env_logger = "0.10.0"
+once_cell = "1.17.2"
+predicates = "3.0.3"
+rstest = "0.17.0"
+test-log = "0.2.11"
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(ci)'] }