fix(shell): improve docker access diagnostics and e2e paths

Author: skulidropek

packages/lib/src/shell/docker.ts

@@ -5,6 +5,7 @@ import type { PlatformError } from "@effect/platform/Error"
 import { Effect, pipe } from "effect"
 import * as Chunk from "effect/Chunk"
 import * as Stream from "effect/Stream"
+import { existsSync } from "node:fs"
 
 import { runCommandCapture, runCommandWithExitCodes } from "./command-runner.js"
 import { CommandFailedError, DockerAccessError, type DockerAccessIssue, DockerCommandError } from "./errors.js"
@@ -39,6 +40,67 @@ const collectUint8Array = (chunks: Chunk.Chunk<Uint8Array>): Uint8Array =>
 
 const permissionDeniedPattern = /permission denied/i
 
+const resolveDockerHostFallback = (): string | undefined => {
+  if (process.env["DOCKER_HOST"] !== undefined) {
+    return undefined
+  }
+
+  const runtimeDir = process.env["XDG_RUNTIME_DIR"]?.trim()
+  const uid =
+    typeof process.getuid === "function"
+      ? process.getuid().toString()
+      : process.env["UID"]?.trim()
+
+  const candidates = Array.from(
+    new Set(
+      [
+        runtimeDir ? `${runtimeDir}/docker.sock` : undefined,
+        uid ? `/run/user/${uid}/docker.sock` : undefined
+      ].filter((value): value is string => value !== undefined)
+    )
+  )
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return `unix://${candidate}`
+    }
+  }
+
+  return undefined
+}
+
+const runDockerInfoCommand = (
+  cwd: string,
+  env?: Readonly<Record<string, string | undefined>>
+): Effect.Effect<{ readonly exitCode: number; readonly details: string }, PlatformError, CommandExecutor.CommandExecutor> =>
+  Effect.scoped(
+    Effect.gen(function*(_) {
+      const executor = yield* _(CommandExecutor.CommandExecutor)
+      const process = yield* _(
+        executor.start(
+          pipe(
+            Command.make("docker", "info"),
+            Command.workingDirectory(cwd),
+            env ? Command.env(env) : (value) => value,
+            Command.stdin("pipe"),
+            Command.stdout("pipe"),
+            Command.stderr("pipe")
+          )
+        )
+      )
+
+      const stderrBytes = yield* _(
+        pipe(process.stderr, Stream.runCollect, Effect.map((chunks) => collectUint8Array(chunks)))
+      )
+      const exitCode = Number(yield* _(process.exitCode))
+      const stderr = new TextDecoder("utf-8").decode(stderrBytes).trim()
+      return {
+        exitCode,
+        details: stderr.length > 0 ? stderr : `docker info failed with exit code ${exitCode}`
+      }
+    })
+  )
+
 // CHANGE: classify docker daemon access failure into deterministic typed reasons
 // WHY: allow callers to render actionable recovery guidance for socket permission issues
 // QUOTE(ТЗ): "docker-git handles Docker socket permission problems predictably"
@@ -67,35 +129,43 @@ export const ensureDockerDaemonAccess = (
 ): Effect.Effect<void, DockerAccessError | PlatformError, CommandExecutor.CommandExecutor> =>
   Effect.scoped(
     Effect.gen(function*(_) {
-      const executor = yield* _(CommandExecutor.CommandExecutor)
-      const process = yield* _(
-        executor.start(
-          pipe(
-            Command.make("docker", "info"),
-            Command.workingDirectory(cwd),
-            Command.stdin("pipe"),
-            Command.stdout("pipe"),
-            Command.stderr("pipe")
-          )
-        )
-      )
+      const primaryResult = yield* _(runDockerInfoCommand(cwd))
+      if (primaryResult.exitCode === 0) {
+        return
+      }
 
-      const stderrBytes = yield* _(
-        pipe(process.stderr, Stream.runCollect, Effect.map((chunks) => collectUint8Array(chunks)))
-      )
-      const exitCode = Number(yield* _(process.exitCode))
+      const primaryIssue = classifyDockerAccessIssue(primaryResult.details)
+      if (primaryIssue === "PermissionDenied" && process.env["DOCKER_HOST"] === undefined) {
+        const fallbackHost = resolveDockerHostFallback()
+        if (fallbackHost !== undefined) {
+          const fallbackResult = yield* _(
+            runDockerInfoCommand(cwd, {
+              ...process.env,
+              DOCKER_HOST: fallbackHost
+            })
+          )
 
-      if (exitCode === 0) {
-        return
+          if (fallbackResult.exitCode === 0) {
+            process.env["DOCKER_HOST"] = fallbackHost
+            return
+          }
+
+          return yield* _(
+            Effect.fail(
+              new DockerAccessError({
+                issue: classifyDockerAccessIssue(fallbackResult.details),
+                details: fallbackResult.details
+              })
+            )
+          )
+        }
       }
 
-      const stderr = new TextDecoder("utf-8").decode(stderrBytes).trim()
-      const details = stderr.length > 0 ? stderr : `docker info failed with exit code ${exitCode}`
       return yield* _(
         Effect.fail(
           new DockerAccessError({
-            issue: classifyDockerAccessIssue(details),
-            details
+            issue: primaryIssue,
+            details: primaryResult.details
           })
         )
       )

packages/lib/src/usecases/errors.ts

@@ -54,6 +54,26 @@ const renderDockerAccessHeadline = (issue: DockerAccessError["issue"]): string =
     ? "Cannot access Docker daemon socket: permission denied."
     : "Cannot connect to Docker daemon."
 
+const renderDockerAccessActionPlan = (issue: DockerAccessError["issue"]): string => {
+  const permissionDeniedPlan = [
+    "Action plan:",
+    "1) In the same shell, run: `groups $USER` and make sure group `docker` is present.",
+    "2) Re-login to refresh group memberships and run command again.",
+    "3) If DOCKER_HOST is set to rootless socket, keep running: `export DOCKER_HOST=unix:///run/user/$UID/docker.sock`.",
+    "4) If using a dedicated socket not in /run/user, set DOCKER_HOST explicitly and re-run.",
+    "Tip: this app now auto-tries a rootless socket fallback on first permission error."
+  ]
+
+  const daemonUnavailablePlan = [
+    "Action plan:",
+    "1) Check daemon status: `systemctl --user status docker` or `systemctl status docker`.",
+    "2) Start daemon: `systemctl --user start docker` (or `systemctl start docker` for system Docker).",
+    "3) Retry command in a new shell."
+  ]
+
+  return issue === "PermissionDenied" ? permissionDeniedPlan.join("\n") : daemonUnavailablePlan.join("\n")
+}
+
 const renderPrimaryError = (error: NonParseError): string | null =>
   Match.value(error).pipe(
     Match.when({ _tag: "FileExistsError" }, ({ path }) => `File already exists: ${path} (use --force to overwrite)`),
@@ -68,6 +88,7 @@ const renderPrimaryError = (error: NonParseError): string | null =>
         renderDockerAccessHeadline(issue),
         "Hint: ensure Docker daemon is running and current user can access the docker socket.",
         "Hint: if you use rootless Docker, set DOCKER_HOST to your user socket (for example unix:///run/user/$UID/docker.sock).",
+        renderDockerAccessActionPlan(issue),
         `Details: ${details}`
       ].join("\n")),
     Match.when({ _tag: "CloneFailedError" }, ({ repoRef, repoUrl, targetDir }) =>

scripts/e2e/clone-cache.sh

@@ -21,7 +21,7 @@ export DOCKER_GIT_PROJECTS_ROOT="$ROOT"
 export DOCKER_GIT_STATE_AUTO_SYNC=0
 
 REPO_URL="https://github.com/octocat/Hello-World/issues/1"
-TARGET_DIR="/home/dev/octocat/hello-world/issue-1"
+TARGET_DIR="/home/dev/.docker-git/workspaces/octocat/hello-world/issue-1"
 MIRROR_PREFIX="/home/dev/.docker-git/.cache/git-mirrors"
 
 ACTIVE_OUT_DIR=""

scripts/e2e/opencode-autoconnect.sh

@@ -25,7 +25,7 @@ export DOCKER_GIT_PROJECTS_ROOT="$ROOT"
 export DOCKER_GIT_STATE_AUTO_SYNC=0
 
 REPO_URL="https://github.com/octocat/Hello-World/issues/1"
-TARGET_DIR="/home/dev/octocat/hello-world/issue-1"
+TARGET_DIR="/home/dev/.docker-git/workspaces/octocat/hello-world/issue-1"
 E2E_BIN="$ROOT/.e2e-bin"
 dg_ensure_docker "$E2E_BIN"