feat(core): isolate issue/pr workspaces for parallel work

Author: skulidropek

README.md

@@ -20,10 +20,21 @@ pnpm run docker-git
 # Clone a repo into its own container (creates under ~/.docker-git)
 pnpm run docker-git clone https://github.com/agiens/crm/tree/vova-fork --force
 
+# Clone an issue URL (creates isolated workspace + issue branch)
+pnpm run docker-git clone https://github.com/agiens/crm/issues/123 --force
+
 # Same, but also enable Playwright MCP + Chromium sidecar for Codex
 pnpm run docker-git clone https://github.com/agiens/crm/tree/vova-fork --force --mcp-playwright
 ```
 
+## Parallel Issues / PRs
+
+When you clone GitHub issue or PR URLs, docker-git creates isolated project paths and container names:
+- `.../issues/123` -> `<projectsRoot>/<owner>/<repo>/issue-123` (branch `issue-123`)
+- `.../pull/45` -> `<projectsRoot>/<owner>/<repo>/pr-45` (ref `refs/pull/45/head`)
+
+This lets you run multiple issues/PRs for the same repository in parallel without container/path collisions.
+
 ## Projects Root Layout
 
 The projects root is:

packages/app/src/docker-git/cli/parser-clone.ts

@@ -13,13 +13,23 @@ import {
 import { parseRawOptions } from "./parser-options.js"
 import { splitPositionalRepo } from "./parser-shared.js"
 
-const applyCloneDefaults = (raw: RawOptions, repoUrl: string): RawOptions => {
-  const repoPath = deriveRepoPathParts(repoUrl).pathParts.join("/")
+const resolveCloneRepoPath = (resolvedRepo: ReturnType<typeof resolveRepoInput>): string => {
+  const baseParts = deriveRepoPathParts(resolvedRepo.repoUrl).pathParts
+  const projectParts = resolvedRepo.workspaceSuffix ? [...baseParts, resolvedRepo.workspaceSuffix] : baseParts
+  return projectParts.join("/")
+}
+
+const applyCloneDefaults = (
+  raw: RawOptions,
+  rawRepoUrl: string,
+  resolvedRepo: ReturnType<typeof resolveRepoInput>
+): RawOptions => {
+  const repoPath = resolveCloneRepoPath(resolvedRepo)
   const sshUser = raw.sshUser?.trim() ?? defaultTemplateConfig.sshUser
   const homeDir = `/home/${sshUser}`
   return {
     ...raw,
-    repoUrl,
+    repoUrl: rawRepoUrl,
     outDir: raw.outDir ?? `.docker-git/${repoPath}`,
     targetDir: raw.targetDir ?? `${homeDir}/${repoPath}`
   }
@@ -42,7 +52,7 @@ export const parseClone = (args: ReadonlyArray<string>): Either.Either<Command,
     const raw = yield* _(parseRawOptions(restArgs))
     const rawRepoUrl = yield* _(nonEmpty("--repo-url", raw.repoUrl ?? positionalRepoUrl))
     const resolvedRepo = resolveRepoInput(rawRepoUrl)
-    const withDefaults = applyCloneDefaults(raw, resolvedRepo.repoUrl)
+    const withDefaults = applyCloneDefaults(raw, rawRepoUrl, resolvedRepo)
     const withRef = resolvedRepo.repoRef !== undefined && raw.repoRef === undefined
       ? { ...withDefaults, repoRef: resolvedRepo.repoRef }
       : withDefaults

packages/app/src/docker-git/cli/parser-shared.ts

@@ -24,10 +24,19 @@ export const parseProjectDirWithOptions = (
     const { positionalRepoUrl, restArgs } = splitPositionalRepo(args)
     const raw = yield* _(parseRawOptions(restArgs))
     const rawRepoUrl = raw.repoUrl ?? positionalRepoUrl
-    const resolvedRepo = rawRepoUrl ? resolveRepoInput(rawRepoUrl).repoUrl : null
+    const resolvedRepo = rawRepoUrl ? resolveRepoInput(rawRepoUrl) : null
+    const repoPath = resolvedRepo
+      ? (() => {
+          const baseParts = deriveRepoPathParts(resolvedRepo.repoUrl).pathParts
+          const projectParts = resolvedRepo.workspaceSuffix
+            ? [...baseParts, resolvedRepo.workspaceSuffix]
+            : baseParts
+          return projectParts.join("/")
+        })()
+      : null
     const projectDir = raw.projectDir ??
-      (resolvedRepo
-        ? `.docker-git/${deriveRepoPathParts(resolvedRepo).pathParts.join("/")}`
+      (repoPath
+        ? `.docker-git/${repoPath}`
         : defaultProjectDir)
 
     return { projectDir, raw }

packages/app/src/docker-git/cli/usage.ts

@@ -30,7 +30,7 @@ Commands:
 Options:
   --repo-ref <ref>          Git ref/branch (default: main)
   --branch, -b <ref>        Alias for --repo-ref
-  --target-dir <path>       Target dir inside container (create default: /home/dev/app, clone default: /home/dev/<org>/<repo>)
+  --target-dir <path>       Target dir inside container (create default: /home/dev/app, clone default: /home/dev/<org>/<repo>[/issue-<id>|/pr-<id>])
   --ssh-port <port>         Local SSH port (default: 2222)
   --ssh-user <user>         SSH user inside container (default: dev)
   --container-name <name>   Docker container name (default: dg-<repo>)
@@ -42,7 +42,7 @@ Options:
   --env-project <path>      Host path to project env file (default: ./.orch/env/project.env)
   --codex-auth <path>       Host path for Codex auth cache (default: <projectsRoot>/.orch/auth/codex)
   --codex-home <path>       Container path for Codex auth (default: /home/dev/.codex)
-  --out-dir <path>          Output directory (default: <projectsRoot>/<org>/<repo>)
+  --out-dir <path>          Output directory (default: <projectsRoot>/<org>/<repo>[/issue-<id>|/pr-<id>])
   --project-dir <path>      Project directory for attach (default: .)
   --lines <n>               Tail last N lines for sessions logs (default: 200)
   --include-default         Show default/system processes in sessions list

packages/app/src/docker-git/menu-create.ts

@@ -1,4 +1,4 @@
-import { type CreateCommand, deriveRepoPathParts } from "@effect-template/lib/core/domain"
+import { type CreateCommand, deriveRepoPathParts, resolveRepoInput } from "@effect-template/lib/core/domain"
 import { createProject } from "@effect-template/lib/usecases/actions"
 import type { AppError } from "@effect-template/lib/usecases/errors"
 import { defaultProjectsRoot } from "@effect-template/lib/usecases/menu-helpers"
@@ -91,21 +91,24 @@ const joinPath = (...parts: ReadonlyArray<string>): string => {
 }
 
 const resolveDefaultOutDir = (cwd: string, repoUrl: string): string => {
-  const repoPath = deriveRepoPathParts(repoUrl).pathParts
-  return joinPath(defaultProjectsRoot(cwd), ...repoPath)
+  const resolvedRepo = resolveRepoInput(repoUrl)
+  const baseParts = deriveRepoPathParts(resolvedRepo.repoUrl).pathParts
+  const projectParts = resolvedRepo.workspaceSuffix ? [...baseParts, resolvedRepo.workspaceSuffix] : baseParts
+  return joinPath(defaultProjectsRoot(cwd), ...projectParts)
 }
 
 export const resolveCreateInputs = (
   cwd: string,
   values: Partial<CreateInputs>
 ): CreateInputs => {
   const repoUrl = values.repoUrl ?? ""
+  const resolvedRepoRef = repoUrl.length > 0 ? resolveRepoInput(repoUrl).repoRef : undefined
   const secretsRoot = values.secretsRoot ?? joinPath(defaultProjectsRoot(cwd), "secrets")
   const outDir = values.outDir ?? (repoUrl.length > 0 ? resolveDefaultOutDir(cwd, repoUrl) : "")
 
   return {
     repoUrl,
-    repoRef: values.repoRef ?? "main",
+    repoRef: values.repoRef ?? resolvedRepoRef ?? "main",
     outDir,
     secretsRoot,
     runUp: values.runUp !== false,

packages/app/tests/docker-git/parser.test.ts

@@ -45,6 +45,16 @@ describe("parseArgs", () => {
       expect(command.config.sshPort).toBe(defaultTemplateConfig.sshPort)
     }))
 
+  it.effect("parses create command with issue url into isolated defaults", () =>
+    expectCreateCommand(["create", "--repo-url", "https://github.com/org/repo/issues/9"], (command) => {
+      expect(command.config.repoUrl).toBe("https://github.com/org/repo.git")
+      expect(command.config.repoRef).toBe("issue-9")
+      expect(command.outDir).toBe(".docker-git/org/repo/issue-9")
+      expect(command.config.containerName).toBe("dg-repo-issue-9")
+      expect(command.config.serviceName).toBe("dg-repo-issue-9")
+      expect(command.config.volumeName).toBe("dg-repo-issue-9-home")
+    }))
+
   it.effect("fails on missing repo url", () =>
     Effect.sync(() => {
       Either.match(parseArgs(["create"]), {
@@ -76,6 +86,37 @@ describe("parseArgs", () => {
       expect(command.config.targetDir).toBe("/home/dev/agiens/crm")
     }))
 
+  it.effect("parses GitHub issue url as isolated project + issue branch", () =>
+    expectCreateCommand(["clone", "https://github.com/org/repo/issues/5"], (command) => {
+      expect(command.config.repoUrl).toBe("https://github.com/org/repo.git")
+      expect(command.config.repoRef).toBe("issue-5")
+      expect(command.outDir).toBe(".docker-git/org/repo/issue-5")
+      expect(command.config.targetDir).toBe("/home/dev/org/repo/issue-5")
+      expect(command.config.containerName).toBe("dg-repo-issue-5")
+      expect(command.config.serviceName).toBe("dg-repo-issue-5")
+      expect(command.config.volumeName).toBe("dg-repo-issue-5-home")
+    }))
+
+  it.effect("parses GitHub PR url as isolated project", () =>
+    expectCreateCommand(["clone", "https://github.com/org/repo/pull/42"], (command) => {
+      expect(command.config.repoUrl).toBe("https://github.com/org/repo.git")
+      expect(command.config.repoRef).toBe("refs/pull/42/head")
+      expect(command.outDir).toBe(".docker-git/org/repo/pr-42")
+      expect(command.config.targetDir).toBe("/home/dev/org/repo/pr-42")
+      expect(command.config.containerName).toBe("dg-repo-pr-42")
+      expect(command.config.serviceName).toBe("dg-repo-pr-42")
+      expect(command.config.volumeName).toBe("dg-repo-pr-42-home")
+    }))
+
+  it.effect("parses attach with GitHub issue url into issue workspace", () =>
+    Effect.sync(() => {
+      const command = parseOrThrow(["attach", "https://github.com/org/repo/issues/7"])
+      if (command._tag !== "Attach") {
+        throw new Error("expected Attach command")
+      }
+      expect(command.projectDir).toBe(".docker-git/org/repo/issue-7")
+    }))
+
   it.effect("parses down-all command", () =>
     Effect.sync(() => {
       const command = parseOrThrow(["down-all"])

packages/lib/src/core/command-builders.ts

@@ -50,6 +50,7 @@ const normalizeSecretsRoot = (value: string): string => trimRightChar(value, "/"
 type RepoBasics = {
   readonly repoUrl: string
   readonly repoSlug: string
+  readonly projectSlug: string
   readonly repoPath: string
   readonly repoRef: string
   readonly targetDir: string
@@ -63,7 +64,10 @@ const resolveRepoBasics = (raw: RawOptions): Either.Either<RepoBasics, ParseErro
     const resolvedRepo = resolveRepoInput(rawRepoUrl)
     const repoUrl = resolvedRepo.repoUrl
     const repoSlug = deriveRepoSlug(repoUrl)
-    const repoPath = deriveRepoPathParts(repoUrl).pathParts.join("/")
+    const repoPathParts = deriveRepoPathParts(repoUrl).pathParts
+    const workspaceSuffix = resolvedRepo.workspaceSuffix
+    const projectSlug = workspaceSuffix ? `${repoSlug}-${workspaceSuffix}` : repoSlug
+    const repoPath = workspaceSuffix ? [...repoPathParts, workspaceSuffix].join("/") : repoPathParts.join("/")
     const repoRef = yield* _(
       nonEmpty("--repo-ref", raw.repoRef ?? resolvedRepo.repoRef, defaultTemplateConfig.repoRef)
     )
@@ -73,7 +77,7 @@ const resolveRepoBasics = (raw: RawOptions): Either.Either<RepoBasics, ParseErro
     const sshUser = yield* _(nonEmpty("--ssh-user", raw.sshUser, defaultTemplateConfig.sshUser))
     const sshPort = yield* _(parsePort(raw.sshPort ?? String(defaultTemplateConfig.sshPort)))
 
-    return { repoUrl, repoSlug, repoPath, repoRef, targetDir, sshUser, sshPort }
+    return { repoUrl, repoSlug, projectSlug, repoPath, repoRef, targetDir, sshUser, sshPort }
   })
 
 type NameConfig = {
@@ -84,12 +88,12 @@ type NameConfig = {
 
 const resolveNames = (
   raw: RawOptions,
-  repoSlug: string
+  projectSlug: string
 ): Either.Either<NameConfig, ParseError> =>
   Either.gen(function*(_) {
-    const derivedContainerName = `dg-${repoSlug}`
-    const derivedServiceName = `dg-${repoSlug}`
-    const derivedVolumeName = `dg-${repoSlug}-home`
+    const derivedContainerName = `dg-${projectSlug}`
+    const derivedServiceName = `dg-${projectSlug}`
+    const derivedVolumeName = `dg-${projectSlug}-home`
     const containerName = yield* _(
       nonEmpty("--container-name", raw.containerName, derivedContainerName)
     )
@@ -111,7 +115,7 @@ type PathConfig = {
 
 const resolvePaths = (
   raw: RawOptions,
-  repoSlug: string,
+  projectSlug: string,
   repoPath: string
 ): Either.Either<PathConfig, ParseError> =>
   Either.gen(function*(_) {
@@ -127,7 +131,7 @@ const resolvePaths = (
       : `${normalizedSecretsRoot}/global.env`
     const defaultEnvProjectPath = normalizedSecretsRoot === undefined
       ? defaultTemplateConfig.envProjectPath
-      : `${normalizedSecretsRoot}/${repoSlug}.env`
+      : `${normalizedSecretsRoot}/${projectSlug}.env`
     const defaultCodexAuthPath = normalizedSecretsRoot === undefined
       ? defaultTemplateConfig.codexAuthPath
       : `${normalizedSecretsRoot}/codex`
@@ -163,8 +167,8 @@ export const buildCreateCommand = (
 ): Either.Either<CreateCommand, ParseError> =>
   Either.gen(function*(_) {
     const repo = yield* _(resolveRepoBasics(raw))
-    const names = yield* _(resolveNames(raw, repo.repoSlug))
-    const paths = yield* _(resolvePaths(raw, repo.repoSlug, repo.repoPath))
+    const names = yield* _(resolveNames(raw, repo.projectSlug))
+    const paths = yield* _(resolvePaths(raw, repo.projectSlug, repo.repoPath))
     const runUp = raw.up ?? true
     const force = raw.force ?? false
     const enableMcpPlaywright = raw.enableMcpPlaywright ?? false

packages/lib/src/core/repo.ts

@@ -205,9 +205,10 @@ export const parseGithubRepoUrl = (input: string): GithubRepo | null => {
   return { owner, repo }
 }
 
-type ResolvedRepoInput = {
+export type ResolvedRepoInput = {
   readonly repoUrl: string
   readonly repoRef?: string
+  readonly workspaceSuffix?: string
 }
 
 type GithubRefParts = {
@@ -244,9 +245,11 @@ const parseGithubPrUrl = (input: string): ResolvedRepoInput | null => {
   }
 
   const repo = stripGitSuffix(parsed.repoRaw)
+  const workspaceSuffix = `pr-${slugify(parsed.ref)}`
   return {
     repoUrl: `https://github.com/${parsed.owner}/${repo}.git`,
-    repoRef: `refs/pull/${parsed.ref}/head`
+    repoRef: `refs/pull/${parsed.ref}/head`,
+    workspaceSuffix
   }
 }
 
@@ -278,7 +281,7 @@ const parseGithubTreeUrl = (input: string): ResolvedRepoInput | null => {
 // FORMAT THEOREM: ∀u: issue(u) → repo(u)
 // PURITY: CORE
 // EFFECT: n/a
-// INVARIANT: issue URL yields repoUrl without repoRef
+// INVARIANT: issue URL yields repoUrl + deterministic issue branch
 // COMPLEXITY: O(n) where n = |url|
 const parseGithubIssueUrl = (input: string): ResolvedRepoInput | null => {
   const parsed = parseGithubRefParts(input)
@@ -287,7 +290,12 @@ const parseGithubIssueUrl = (input: string): ResolvedRepoInput | null => {
   }
 
   const repo = stripGitSuffix(parsed.repoRaw)
-  return { repoUrl: `https://github.com/${parsed.owner}/${repo}.git` }
+  const workspaceSuffix = `issue-${slugify(parsed.ref)}`
+  return {
+    repoUrl: `https://github.com/${parsed.owner}/${repo}.git`,
+    repoRef: workspaceSuffix,
+    workspaceSuffix
+  }
 }
 
 // CHANGE: normalize repo input and PR/issue URLs into repo + ref

packages/lib/src/core/templates-entrypoint/tasks.ts

@@ -71,6 +71,11 @@ const renderCloneBodyRef = (config: TemplateConfig): string =>
           if ! su - ${config.sshUser} -c "GIT_TERMINAL_PROMPT=0 git clone --progress --branch '$DEFAULT_BRANCH' '$AUTH_REPO_URL' '$TARGET_DIR'"; then
             echo "[clone] git clone failed for $REPO_URL"
             CLONE_OK=0
+          elif [[ "$REPO_REF" == issue-* ]]; then
+            if ! su - ${config.sshUser} -c "cd '$TARGET_DIR' && git checkout -B '$REPO_REF'"; then
+              echo "[clone] failed to create local branch '$REPO_REF'"
+              CLONE_OK=0
+            fi
           fi
         else
           echo "[clone] git clone failed for $REPO_URL"