fix(shell): avoid docker SSH port collisions and improve docker compose hints (#71)

* feat(ui): add project list scrolling and shorten prompt paths

* fix(shell): avoid docker SSH port collisions and improve hints

* fix(lint): satisfy effect and unicorn rules for docker port fallback

Author: skulidropek

packages/lib/src/shell/docker.ts

@@ -440,3 +440,76 @@ export const runDockerPsNames = (
         .filter((line) => line.length > 0)
     )
   )
+
+const publishedHostPortPattern = /:(\d+)->/g
+
+const parsePublishedHostPortsFromLine = (line: string): ReadonlyArray<number> => {
+  const parsed: Array<number> = []
+  for (const match of line.matchAll(publishedHostPortPattern)) {
+    const rawPort = match[1]
+    if (rawPort === undefined) {
+      continue
+    }
+    const value = Number.parseInt(rawPort, 10)
+    if (Number.isInteger(value) && value > 0 && value <= 65_535) {
+      parsed.push(value)
+    }
+  }
+  return parsed
+}
+
+// CHANGE: decode published host ports from `docker ps --format "{{.Ports}}"` output
+// WHY: Docker can reserve host ports via NAT even when no host TCP socket is visible
+// QUOTE(ТЗ): "должен просто новый порт брать под себя"
+// REF: user-request-2026-02-19-port-allocation
+// SOURCE: n/a
+// FORMAT THEOREM: forall p in parse(output): published_by_docker(p)
+// PURITY: CORE
+// EFFECT: Effect<ReadonlyArray<number>, never, never>
+// INVARIANT: returns unique ports in encounter order
+// COMPLEXITY: O(|output|)
+export const parseDockerPublishedHostPorts = (output: string): ReadonlyArray<number> => {
+  const unique = new Set<number>()
+  const parsed: Array<number> = []
+
+  for (const line of output.split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (trimmed.length === 0) {
+      continue
+    }
+    for (const port of parsePublishedHostPortsFromLine(trimmed)) {
+      if (!unique.has(port)) {
+        unique.add(port)
+        parsed.push(port)
+      }
+    }
+  }
+
+  return parsed
+}
+
+// CHANGE: read currently published Docker host ports from running containers
+// WHY: avoid false "free port" results when Docker reserves ports without userland proxy sockets
+// QUOTE(ТЗ): "а не сражаться за старый"
+// REF: user-request-2026-02-19-port-allocation
+// SOURCE: n/a
+// FORMAT THEOREM: forall p in result: published_by_running_container(p)
+// PURITY: SHELL
+// EFFECT: Effect<ReadonlyArray<number>, CommandFailedError | PlatformError, CommandExecutor>
+// INVARIANT: output ports are unique
+// COMPLEXITY: O(command + |stdout|)
+export const runDockerPsPublishedHostPorts = (
+  cwd: string
+): Effect.Effect<ReadonlyArray<number>, CommandFailedError | PlatformError, CommandExecutor.CommandExecutor> =>
+  pipe(
+    runCommandCapture(
+      {
+        cwd,
+        command: "docker",
+        args: ["ps", "--format", "{{.Ports}}"]
+      },
+      [Number(ExitCode(0))],
+      (exitCode) => new CommandFailedError({ command: "docker ps", exitCode })
+    ),
+    Effect.map((output) => parseDockerPublishedHostPorts(output))
+  )

packages/lib/src/usecases/actions/ports.ts

@@ -1,3 +1,4 @@
+import type * as CommandExecutor from "@effect/platform/CommandExecutor"
 import type { PlatformError } from "@effect/platform/Error"
 import type * as FileSystem from "@effect/platform/FileSystem"
 import type * as Path from "@effect/platform/Path"
@@ -15,7 +16,7 @@ export const resolveSshPort = (
 ): Effect.Effect<
   CreateCommand["config"],
   PortProbeError | PlatformError,
-  FileSystem.FileSystem | Path.Path
+  FileSystem.FileSystem | Path.Path | CommandExecutor.CommandExecutor
 > =>
   Effect.gen(function*(_) {
     const reserved = yield* _(loadReservedPorts(outDir))

packages/lib/src/usecases/errors.ts

@@ -60,7 +60,8 @@ const renderPrimaryError = (error: NonParseError): string | null =>
     Match.when({ _tag: "DockerCommandError" }, ({ exitCode }) =>
       [
         `docker compose failed with exit code ${exitCode}`,
-        "Hint: ensure Docker daemon is running and current user can access /var/run/docker.sock (for example via the docker group)."
+        "Hint: ensure Docker daemon is running and current user can access /var/run/docker.sock (for example via the docker group).",
+        "Hint: if output above contains 'port is already allocated', retry with a free SSH port via --ssh-port <port> (for example --ssh-port 2235), or stop the conflicting project/container."
       ].join("\n")),
     Match.when({ _tag: "DockerAccessError" }, ({ details, issue }) =>
       [

packages/lib/src/usecases/ports-reserve.ts

@@ -1,8 +1,10 @@
+import type * as CommandExecutor from "@effect/platform/CommandExecutor"
 import type { PlatformError } from "@effect/platform/Error"
 import type { FileSystem } from "@effect/platform/FileSystem"
 import * as Path from "@effect/platform/Path"
-import { Effect, Option } from "effect"
+import { Effect, Either, Option } from "effect"
 
+import { runDockerPsPublishedHostPorts } from "../shell/docker.js"
 import { PortProbeError } from "../shell/errors.js"
 import { isPortAvailable } from "../shell/ports.js"
 import { listProjectItems } from "./projects-list.js"
@@ -12,6 +14,8 @@ export type ReservedPort = {
   readonly projectDir: string
 }
 
+const dockerPublishedMarker = "<docker:published>"
+
 const resolveExclude = (
   path: Path.Path,
   excludeDir: string | null
@@ -29,38 +33,74 @@ const filterReserved = (
   return path.resolve(item.projectDir) !== resolvedExclude
 }
 
+const reservePort = (
+  reserved: Array<ReservedPort>,
+  seen: Set<number>,
+  port: number,
+  projectDir: string
+): void => {
+  if (seen.has(port)) {
+    return
+  }
+  seen.add(port)
+  reserved.push({ port, projectDir })
+}
+
+const loadPublishedDockerPorts = (): Effect.Effect<ReadonlySet<number>, never, CommandExecutor.CommandExecutor> =>
+  Effect.either(runDockerPsPublishedHostPorts(process.cwd())).pipe(
+    Effect.flatMap(
+      Either.match({
+        onLeft: (error) =>
+          Effect.logWarning(
+            `Failed to read published Docker ports; falling back to TCP probing only: ${
+              error instanceof Error ? error.message : String(error)
+            }`
+          ).pipe(Effect.as(new Set<number>())),
+        onRight: (ports) => Effect.succeed(new Set(ports))
+      })
+    )
+  )
+
 // CHANGE: collect SSH ports currently occupied by existing docker-git projects
 // WHY: avoid port collisions while allowing reuse of ports from stopped projects
 // QUOTE(ТЗ): "для каждого докера брать должен свой порт"
 // REF: user-request-2026-02-05-port-reserve
 // SOURCE: n/a
 // FORMAT THEOREM: ∀p∈Projects: reserved(port(p))
 // PURITY: SHELL
-// EFFECT: Effect<ReadonlyArray<ReservedPort>, PlatformError | PortProbeError, FileSystem | Path.Path>
+// EFFECT: Effect<ReadonlyArray<ReservedPort>, PlatformError | PortProbeError, FileSystem | Path.Path | CommandExecutor>
 // INVARIANT: excludes the current project dir when provided
 // COMPLEXITY: O(n) where n = number of projects
 export const loadReservedPorts = (
   excludeDir: string | null
 ): Effect.Effect<
   ReadonlyArray<ReservedPort>,
   PlatformError | PortProbeError,
-  FileSystem | Path.Path
+  FileSystem | Path.Path | CommandExecutor.CommandExecutor
 > =>
   Effect.gen(function*(_) {
     const path = yield* _(Path.Path)
     const items = yield* _(listProjectItems)
+    const publishedByDocker = yield* _(loadPublishedDockerPorts())
     const reserved: Array<ReservedPort> = []
+    const seen = new Set<number>()
     const filter = filterReserved(path, excludeDir)
 
     for (const item of items) {
       if (!filter(item)) {
         continue
       }
-      if (!(yield* _(isPortAvailable(item.sshPort)))) {
-        reserved.push({ port: item.sshPort, projectDir: item.projectDir })
+      const occupiedByDocker = publishedByDocker.has(item.sshPort)
+      const occupiedBySocket = occupiedByDocker ? false : !(yield* _(isPortAvailable(item.sshPort)))
+      if (occupiedByDocker || occupiedBySocket) {
+        reservePort(reserved, seen, item.sshPort, item.projectDir)
       }
     }
 
+    for (const port of publishedByDocker) {
+      reservePort(reserved, seen, port, dockerPublishedMarker)
+    }
+
     return reserved
   })
 

packages/lib/src/usecases/projects-up.ts

@@ -33,7 +33,7 @@ const maxPortAttempts = 25
 // SOURCE: n/a
 // FORMAT THEOREM: ∀p: reserved(p) ∨ occupied(p) → selected(p') ∧ available(p')
 // PURITY: SHELL
-// EFFECT: Effect<TemplateConfig, PortProbeError | PlatformError | FileExistsError, FileSystem | Path>
+// EFFECT: Effect<TemplateConfig, PortProbeError | PlatformError | FileExistsError, FileSystem | Path | CommandExecutor>
 // INVARIANT: config is rewritten when port changes
 // COMPLEXITY: O(n) where n = maxPortAttempts
 const ensureAvailableSshPort = (
@@ -42,7 +42,7 @@ const ensureAvailableSshPort = (
 ): Effect.Effect<
   TemplateConfig,
   PortProbeError | PlatformError | FileExistsError,
-  FileSystem | Path
+  FileSystem | Path | CommandExecutor
 > =>
   Effect.gen(function*(_) {
     const reserved = yield* _(loadReservedPorts(projectDir))

packages/lib/tests/shell/docker.test.ts

@@ -1,9 +1,26 @@
 import { describe, expect, it } from "@effect/vitest"
 
-import { dockerComposeUpRecreateArgs } from "../../src/shell/docker.js"
+import { dockerComposeUpRecreateArgs, parseDockerPublishedHostPorts } from "../../src/shell/docker.js"
 
 describe("docker compose args", () => {
   it("uses build when force-env recreates containers", () => {
     expect(dockerComposeUpRecreateArgs).toEqual(["up", "-d", "--build", "--force-recreate"])
   })
 })
+
+describe("parseDockerPublishedHostPorts", () => {
+  it("extracts unique published host ports from docker ps output", () => {
+    const output = [
+      "127.0.0.1:2222->22/tcp",
+      "0.0.0.0:5672->5672/tcp, [::]:5672->5672/tcp",
+      "5900/tcp, 6080/tcp, 9223/tcp",
+      ":::8080->80/tcp"
+    ].join("\n")
+
+    expect(parseDockerPublishedHostPorts(output)).toEqual([2222, 5672, 8080])
+  })
+
+  it("returns empty array when no host ports are published", () => {
+    expect(parseDockerPublishedHostPorts("5900/tcp, 6080/tcp")).toEqual([])
+  })
+})

packages/lib/tests/usecases/errors.test.ts

@@ -9,6 +9,8 @@ describe("renderError", () => {
 
     expect(message).toContain("docker compose failed with exit code 1")
     expect(message).toContain("/var/run/docker.sock")
+    expect(message).toContain("port is already allocated")
+    expect(message).toContain("--ssh-port")
   })
 
   it("renders actionable recovery for DockerAccessError", () => {