Add Windows container support with osType option to fix Docker path issues (#1896)

* Initial plan

* Fix Docker container CWD path issue #1873 - use POSIX paths for Linux containers

Co-authored-by: deyaaeldeen <6074665+deyaaeldeen@users.noreply.github.com>

* Add osType option to ContainerOptions for Windows container support

- Add osType?: "unix" | "windows" option to ContainerOptions interface
- Default to "unix" for backward compatibility with existing Linux containers
- Use appropriate path separators in docker.ts based on osType
- Update comprehensive tests for both Unix and Windows container path handling
- Update all type definition files to include new option

Addresses feedback: Windows containers need backslash path separators,
while Unix containers need forward slash separators.

Co-authored-by: deyaaeldeen <6074665+deyaaeldeen@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: deyaaeldeen <6074665+deyaaeldeen@users.noreply.github.com>
Co-authored-by: Peli de Halleux <pelikhan@users.noreply.github.com>

Author: 3 people

docs/public/genaiscript.d.ts

@@ -5182,6 +5182,12 @@ export interface ContainerOptions {
    * Commands to executes after the container is created
    */
   postCreateCommands?: ElementOrArray<string>;
+
+  /**
+   * Container operating system type. Determines path separator used for working directories.
+   * Defaults to "unix" for compatibility with most Linux-based containers.
+   */
+  osType?: "unix" | "windows";
 }
 
 export interface PromiseQueue {

docs/src/content/docs/guides/genaiscript.d.ts

@@ -35,7 +35,7 @@ import type {
   ShellOutput,
   TraceOptions,
 } from "@genaiscript/core";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve, posix, win32 } from "node:path";
 const dbg = genaiscriptDebug("docker");
 
 type DockerodeType = import("dockerode");
@@ -261,10 +261,11 @@ export class DockerManager {
       postCreateCommands,
       env,
       networkEnabled,
+      osType,
     } = options;
     let name = (userName || image).replace(/[^a-zA-Z0-9]+/g, "_");
     if (persistent) {
-      name += `_${await hash({ image, name, ports, env, networkEnabled, postCreateCommands, CORE_VERSION }, { length: 12, version: true })}`;
+      name += `_${await hash({ image, name, ports, env, networkEnabled, postCreateCommands, osType, CORE_VERSION }, { length: 12, version: true })}`;
     } else {
       name += `_${generateId()}`;
     }
@@ -368,7 +369,7 @@ export class DockerManager {
     name: string,
     hostPath: string,
   ): Promise<ContainerHost> {
-    const { trace, persistent } = options;
+    const { trace, persistent, osType = "unix" } = options;
     const dbgc = name ? dbg.extend(name) : dbg;
     const runtimeHost = resolveRuntimeHost();
 
@@ -436,7 +437,10 @@ export class DockerManager {
       }
 
       const { cwd: userCwd, label } = options || {};
-      const cwd = "/" + join(DOCKER_CONTAINER_VOLUME, userCwd || ".");
+      // Use appropriate path separator based on container OS type
+      const pathJoin = osType === "windows" ? win32.join : posix.join;
+      const pathSeparator = osType === "windows" ? "\\" : "/";
+      const cwd = pathSeparator + pathJoin(DOCKER_CONTAINER_VOLUME, userCwd || ".");
 
       try {
         trace?.startDetails(`📦 ▶️ container exec: ${userCwd || ""}> ${label || command}`);

genaiscript.d.ts

@@ -0,0 +1,122 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { test, describe } from "vitest"
+import { expect } from "vitest"
+import { posix, win32 } from "node:path"
+
+describe("docker path handling", () => {
+    test("container working directory uses POSIX paths for Unix containers", () => {
+        // Test that we're using POSIX path joining for container paths
+        const DOCKER_CONTAINER_VOLUME = "app"
+        const osType = "unix"
+        
+        // Simulate various user cwd inputs that could cause issues on Windows
+        const testCases = [
+            { userCwd: "tmp/project", expected: "/app/tmp/project" },
+            { userCwd: "tmp\\windows\\path", expected: "/app/tmp\\windows\\path" }, // Backslashes should be preserved as-is, not converted
+            { userCwd: "some/deep/path/structure", expected: "/app/some/deep/path/structure" },
+            { userCwd: "", expected: "/app" }, // posix.join normalizes empty string
+            { userCwd: undefined, expected: "/app" }, // posix.join("app", ".") normalizes to "app"
+        ]
+        
+        testCases.forEach(({ userCwd, expected }) => {
+            // This simulates the logic from docker.ts
+            const pathJoin = osType === "windows" ? win32.join : posix.join;
+            const pathSeparator = osType === "windows" ? "\\" : "/";
+            const cwd = pathSeparator + pathJoin(DOCKER_CONTAINER_VOLUME, userCwd || ".");
+            expect(cwd).toBe(expected)
+        })
+    })
+
+    test("container working directory uses Windows paths for Windows containers", () => {
+        // Test that we're using Windows path joining for Windows containers
+        const DOCKER_CONTAINER_VOLUME = "app"
+        const osType = "windows"
+        
+        // Simulate various user cwd inputs for Windows containers
+        const testCases = [
+            { userCwd: "tmp/project", expected: "\\app\\tmp\\project" },
+            { userCwd: "tmp\\windows\\path", expected: "\\app\\tmp\\windows\\path" },
+            { userCwd: "some/deep/path/structure", expected: "\\app\\some\\deep\\path\\structure" },
+            { userCwd: "", expected: "\\app" },
+            { userCwd: undefined, expected: "\\app" },
+        ]
+        
+        testCases.forEach(({ userCwd, expected }) => {
+            // This simulates the logic from docker.ts for Windows containers
+            const pathJoin = osType === "windows" ? win32.join : posix.join;
+            const pathSeparator = osType === "windows" ? "\\" : "/";
+            const cwd = pathSeparator + pathJoin(DOCKER_CONTAINER_VOLUME, userCwd || ".");
+            expect(cwd).toBe(expected)
+        })
+    })
+    
+    test("POSIX join vs regular join behavior", () => {
+        // Verify that posix.join always uses forward slashes regardless of host OS
+        const testPath = posix.join("app", "tmp", "project")
+        expect(testPath).toBe("app/tmp/project")
+        expect(testPath).not.toContain("\\") // Should never contain backslashes
+    })
+
+    test("Windows join behavior", () => {
+        // Verify that win32.join uses backslashes
+        const testPath = win32.join("app", "tmp", "project")
+        expect(testPath).toBe("app\\tmp\\project")
+        expect(testPath).toContain("\\") // Should contain backslashes
+    })
+    
+    test("container path construction with various inputs - Unix", () => {
+        const DOCKER_CONTAINER_VOLUME = "app"
+        const osType = "unix"
+        
+        // Test edge cases that could occur in real usage
+        const edgeCases = [
+            { userCwd: "./", expected: "/app/" }, // posix.join normalizes "./" to "app/"
+            { userCwd: "../", expected: "/./" }, // posix.join("app", "../") resolves to "./"
+            { userCwd: "   ", expected: "/app/   " }, // Spaces should be preserved
+            { userCwd: "folder with spaces", expected: "/app/folder with spaces" },
+        ]
+        
+        edgeCases.forEach(({ userCwd, expected }) => {
+            const pathJoin = osType === "windows" ? win32.join : posix.join;
+            const pathSeparator = osType === "windows" ? "\\" : "/";
+            const cwd = pathSeparator + pathJoin(DOCKER_CONTAINER_VOLUME, userCwd || ".");
+            expect(cwd).toBe(expected)
+        })
+    })
+
+    test("container path construction with various inputs - Windows", () => {
+        const DOCKER_CONTAINER_VOLUME = "app"
+        const osType = "windows"
+        
+        // Test edge cases that could occur in real usage for Windows containers
+        const edgeCases = [
+            { userCwd: "./", expected: "\\app\\" }, // win32.join normalizes "./" to "app\\"
+            { userCwd: "../", expected: "\\.\\" }, // win32.join("app", "../") resolves to ".\\"
+            { userCwd: "   ", expected: "\\app\\   " }, // Spaces should be preserved
+            { userCwd: "folder with spaces", expected: "\\app\\folder with spaces" },
+        ]
+        
+        edgeCases.forEach(({ userCwd, expected }) => {
+            const pathJoin = osType === "windows" ? win32.join : posix.join;
+            const pathSeparator = osType === "windows" ? "\\" : "/";
+            const cwd = pathSeparator + pathJoin(DOCKER_CONTAINER_VOLUME, userCwd || ".");
+            expect(cwd).toBe(expected)
+        })
+    })
+
+    test("default osType should be unix for backward compatibility", () => {
+        // Verify that when osType is undefined, it defaults to unix behavior
+        const DOCKER_CONTAINER_VOLUME = "app"
+        const osType = undefined // Simulate default case
+        const userCwd = "tmp/project"
+        
+        // This should behave like unix (default behavior)
+        const pathJoin = (osType === "windows") ? win32.join : posix.join;
+        const pathSeparator = (osType === "windows") ? "\\" : "/";
+        const cwd = pathSeparator + pathJoin(DOCKER_CONTAINER_VOLUME, userCwd || ".");
+        
+        expect(cwd).toBe("/app/tmp/project") // Should use POSIX paths by default
+    })
+})