🤖 test: add DockerRuntime to runtime integration matrix

Adds a third runtime type (docker) to tests/runtime/runtime.test.ts by spinning up a dedicated docker container with bash+git+timeout and running the existing runtime contract suite against DockerRuntime.

Also aligns DockerRuntime writeFile/resolvePath behavior with the contract tests (symlink-preserving atomic writes and ~ expansion).

Author: ammar-agent

src/node/runtime/DockerRuntime.ts

@@ -190,11 +190,27 @@ export class DockerRuntime extends RemoteRuntime {
     return { process };
   }
 
+  /**
+   * Override buildWriteCommand to preserve symlinks and file permissions.
+   *
+   * This matches SSHRuntime behavior: write through the symlink to the final target,
+   * while keeping the symlink itself intact.
+   */
+  protected buildWriteCommand(quotedPath: string, quotedTempPath: string): string {
+    return `RESOLVED=$(readlink -f ${quotedPath} 2>/dev/null || echo ${quotedPath}) && PERMS=$(stat -c '%a' "$RESOLVED" 2>/dev/null || echo 600) && mkdir -p $(dirname "$RESOLVED") && cat > ${quotedTempPath} && chmod "$PERMS" ${quotedTempPath} && mv ${quotedTempPath} "$RESOLVED"`;
+  }
   // ===== Runtime interface implementations =====
 
   resolvePath(filePath: string): Promise<string> {
-    // Inside container, paths are already absolute
-    // Just return as-is since we use fixed /src path
+    // DockerRuntime uses a fixed workspace base (/src), but we still want reasonable shell-style
+    // behavior for callers that pass "~" or "~/...".
+    if (filePath === "~") {
+      return Promise.resolve("/root");
+    }
+    if (filePath.startsWith("~/")) {
+      return Promise.resolve(path.posix.join("/root", filePath.slice(2)));
+    }
+
     return Promise.resolve(
       filePath.startsWith("/") ? filePath : path.posix.join(CONTAINER_SRC_DIR, filePath)
     );

tests/runtime/runtime.test.ts

@@ -24,6 +24,11 @@ import {
   stopSSHServer,
   type SSHServerConfig,
 } from "./test-fixtures/ssh-fixture";
+import {
+  startDockerRuntimeContainer,
+  stopDockerRuntimeContainer,
+  type DockerRuntimeTestConfig,
+} from "./test-fixtures/docker-fixture";
 import { createTestRuntime, TestWorkspace, type RuntimeType } from "./test-fixtures/test-helpers";
 import { execBuffered, readFileString, writeFileString } from "@/node/utils/runtime/helpers";
 import type { Runtime } from "@/node/runtime/Runtime";
@@ -35,6 +40,9 @@ const describeIntegration = shouldRunIntegrationTests() ? describe : describe.sk
 // SSH server config (shared across all tests)
 let sshConfig: SSHServerConfig | undefined;
 
+// DockerRuntime container config (shared across all tests)
+let dockerConfig: DockerRuntimeTestConfig | undefined;
+
 describeIntegration("Runtime integration tests", () => {
   beforeAll(async () => {
     // Check if Docker is available (required for SSH tests)
@@ -48,24 +56,42 @@ describeIntegration("Runtime integration tests", () => {
     console.log("Starting SSH server container...");
     sshConfig = await startSSHServer();
     console.log(`SSH server ready on port ${sshConfig.port}`);
-  }, 60000); // 60s timeout for Docker operations
+
+    console.log("Starting DockerRuntime test container...");
+    dockerConfig = await startDockerRuntimeContainer();
+    console.log(`DockerRuntime container ready: ${dockerConfig.containerName}`);
+  }, 120000); // 120s timeout for Docker build/start operations
 
   afterAll(async () => {
+    if (dockerConfig) {
+      console.log("Stopping DockerRuntime test container...");
+      await stopDockerRuntimeContainer(dockerConfig);
+    }
+
     if (sshConfig) {
       console.log("Stopping SSH server container...");
       await stopSSHServer(sshConfig);
     }
   }, 30000);
 
-  // Test matrix: Run all tests for both local and SSH runtimes
-  describe.each<{ type: RuntimeType }>([{ type: "local" }, { type: "ssh" }])(
+  // Test matrix: Run all tests for local, SSH, and Docker runtimes
+  describe.each<{ type: RuntimeType }>([{ type: "local" }, { type: "ssh" }, { type: "docker" }])(
     "Runtime: $type",
     ({ type }) => {
       // Helper to create runtime for this test type
       // Use a base working directory - TestWorkspace will create subdirectories as needed
       // For local runtime, use os.tmpdir() which matches where TestWorkspace creates directories
-      const getBaseWorkdir = () => (type === "ssh" ? sshConfig!.workdir : os.tmpdir());
-      const createRuntime = (): Runtime => createTestRuntime(type, getBaseWorkdir(), sshConfig);
+      const getBaseWorkdir = () => {
+        if (type === "ssh") {
+          return sshConfig!.workdir;
+        }
+        if (type === "docker") {
+          return "/src";
+        }
+        return os.tmpdir();
+      };
+      const createRuntime = (): Runtime =>
+        createTestRuntime(type, getBaseWorkdir(), sshConfig, dockerConfig);
 
       describe("exec() - Command execution", () => {
         test.concurrent("captures stdout and stderr separately", async () => {
@@ -201,6 +227,8 @@ describeIntegration("Runtime integration tests", () => {
 
           if (type === "ssh") {
             expect(resolved).toBe("/home/testuser");
+          } else if (type === "docker") {
+            expect(resolved).toBe("/root");
           } else {
             expect(resolved).toBe(os.homedir());
           }

tests/runtime/test-fixtures/docker-fixture.ts

@@ -0,0 +1,100 @@
+/**
+ * Docker container fixture for DockerRuntime integration tests.
+ *
+ * Runs a minimal container with bash + git + timeout available.
+ */
+
+import * as crypto from "crypto";
+import { spawn } from "child_process";
+
+export interface DockerRuntimeTestConfig {
+  image: string;
+  containerName: string;
+}
+
+export async function startDockerRuntimeContainer(): Promise<DockerRuntimeTestConfig> {
+  // Build image used for DockerRuntime tests
+  const dockerfilePath = `${__dirname}/docker-runtime`;
+  const image = "mux-docker-runtime-test";
+
+  await execCommand("docker", ["build", "-t", image, dockerfilePath], { timeout: 60000 });
+
+  const containerName = `mux-docker-runtime-test-${crypto.randomBytes(8).toString("hex")}`;
+
+  // Start container in the background. Image CMD keeps it alive.
+  const runResult = await execCommand(
+    "docker",
+    ["run", "-d", "--name", containerName, "--rm", image],
+    { timeout: 60000 }
+  );
+
+  const containerId = runResult.stdout.trim();
+  if (!containerId) {
+    throw new Error("Failed to start docker runtime test container");
+  }
+
+  // Create /src directory (DockerRuntime expects it)
+  await execCommand("docker", ["exec", containerName, "mkdir", "-p", "/src"], {
+    timeout: 10000,
+  });
+
+  return { image, containerName };
+}
+
+export async function stopDockerRuntimeContainer(config: DockerRuntimeTestConfig): Promise<void> {
+  try {
+    await execCommand("docker", ["stop", config.containerName], { timeout: 30000 });
+  } catch (error) {
+    console.error("Error stopping docker runtime test container:", error);
+  }
+}
+
+function execCommand(
+  command: string,
+  args: string[],
+  options?: { timeout?: number }
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  return new Promise((resolve, reject) => {
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+
+    const child = spawn(command, args);
+
+    const timeout = options?.timeout
+      ? setTimeout(() => {
+          timedOut = true;
+          child.kill();
+          reject(new Error(`Command timed out: ${command} ${args.join(" ")}`));
+        }, options.timeout)
+      : undefined;
+
+    child.stdout.on("data", (data: Buffer) => {
+      stdout += data.toString();
+    });
+
+    child.stderr.on("data", (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    child.on("close", (code) => {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      if (timedOut) {
+        return;
+      }
+      resolve({ stdout, stderr, exitCode: code ?? -1 });
+    });
+
+    child.on("error", (error) => {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      if (timedOut) {
+        return;
+      }
+      reject(error);
+    });
+  });
+}

tests/runtime/test-fixtures/docker-runtime/Dockerfile

@@ -0,0 +1,9 @@
+FROM alpine:latest
+
+# bash is required for mux remote command execution (forces bash)
+# git is needed for runtime contract tests (git init/commit/branch)
+# coreutils provides GNU timeout with -s support
+RUN apk add --no-cache bash git coreutils
+
+# Keep the container alive for the duration of the test suite
+CMD ["sleep", "infinity"]

tests/runtime/test-fixtures/test-helpers.ts

@@ -8,22 +8,25 @@ import * as os from "os";
 import * as path from "path";
 import type { Runtime } from "@/node/runtime/Runtime";
 import { WorktreeRuntime } from "@/node/runtime/WorktreeRuntime";
+import { DockerRuntime } from "@/node/runtime/DockerRuntime";
+import type { DockerRuntimeTestConfig } from "./docker-fixture";
 import { SSHRuntime } from "@/node/runtime/SSHRuntime";
 import type { SSHServerConfig } from "./ssh-fixture";
 
 /**
  * Runtime type for test matrix
  * Note: "local" here means worktree runtime (isolated git worktrees), not project-dir runtime
  */
-export type RuntimeType = "local" | "ssh";
+export type RuntimeType = "local" | "ssh" | "docker";
 
 /**
  * Create runtime instance based on type
  */
 export function createTestRuntime(
   type: RuntimeType,
   workdir: string,
-  sshConfig?: SSHServerConfig
+  sshConfig?: SSHServerConfig,
+  dockerConfig?: DockerRuntimeTestConfig
 ): Runtime {
   switch (type) {
     case "local": {
@@ -43,6 +46,15 @@ export function createTestRuntime(
         port: sshConfig.port,
       });
     }
+    case "docker": {
+      if (!dockerConfig) {
+        throw new Error("Docker config required for Docker runtime");
+      }
+      return new DockerRuntime({
+        image: dockerConfig.image,
+        containerName: dockerConfig.containerName,
+      });
+    }
   }
 }
 
@@ -64,18 +76,20 @@ export class TestWorkspace {
    * Create a test workspace with isolated directory
    */
   static async create(runtime: Runtime, type: RuntimeType): Promise<TestWorkspace> {
-    const isRemote = type === "ssh";
+    const isRemote = type !== "local";
 
     if (isRemote) {
-      // For SSH, create subdirectory in remote workdir
-      // The path is already set in SSHRuntime config
-      // Create a unique subdirectory
+      // For SSH/Docker, create a unique subdirectory in the runtime's filesystem.
       const testId = `test-${Date.now()}-${Math.random().toString(36).substring(7)}`;
-      const workspacePath = `/home/testuser/workspace/${testId}`;
+
+      const workspacePath =
+        type === "ssh" ? `/home/testuser/workspace/${testId}` : `/src/${testId}`;
+
+      const cwd = type === "ssh" ? "/home/testuser" : "/";
 
       // Create directory on remote
       const stream = await runtime.exec(`mkdir -p ${workspacePath}`, {
-        cwd: "/home/testuser",
+        cwd,
         timeout: 30,
       });
       await stream.stdin.close();
@@ -102,8 +116,9 @@ export class TestWorkspace {
     if (this.isRemote) {
       // Remove remote directory
       try {
+        const cwd = this.path.startsWith("/home/testuser") ? "/home/testuser" : "/";
         const stream = await this.runtime.exec(`rm -rf ${this.path}`, {
-          cwd: "/home/testuser",
+          cwd,
           timeout: 60,
         });
         await stream.stdin.close();