feat(app): add open command for existing repo workspaces

Author: skulidropek

README.md

@@ -27,6 +27,9 @@ 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
 
+# Open an existing docker-git project by repo/issue URL (runs up + tmux attach)
+pnpm run docker-git open https://github.com/agiens/crm/issues/123
+
 # Reset only project env defaults (keep workspace volume/data)
 pnpm run docker-git clone https://github.com/agiens/crm/issues/123 --force-env
 

package.json

@@ -15,6 +15,7 @@
     "changeset-publish": "node -e \"if (!process.env.NPM_TOKEN) { console.log('Skipping publish: NPM_TOKEN is not set'); process.exit(0); }\" && changeset publish",
     "changeset-version": "changeset version",
     "clone": "pnpm --filter ./packages/app build && node packages/app/dist/main.js clone",
+    "open": "pnpm --filter ./packages/app build && node packages/app/dist/main.js open",
     "docker-git": "pnpm --filter ./packages/app build:docker-git && node packages/app/dist/src/docker-git/main.js",
     "e2e": "bash scripts/e2e/run-all.sh",
     "e2e:clone-cache": "bash scripts/e2e/clone-cache.sh",

packages/app/package.json

@@ -23,6 +23,7 @@
     "build:docker-git": "vite build --config vite.docker-git.config.ts",
     "check": "pnpm run typecheck",
     "clone": "pnpm -C ../.. run clone",
+    "open": "pnpm -C ../.. run open",
     "docker-git": "node dist/src/docker-git/main.js",
     "list": "pnpm -C ../.. run list",
     "prestart": "pnpm run build",

packages/app/src/app/program.ts

@@ -1,17 +1,17 @@
-import { listProjects, readCloneRequest, runDockerGitClone } from "@effect-template/lib"
+import { listProjects, readCloneRequest, runDockerGitClone, runDockerGitOpen } from "@effect-template/lib"
 import { Console, Effect, Match, pipe } from "effect"
 
 /**
  * Compose the CLI program as a single effect.
  *
- * @returns Effect that either runs docker-git clone or prints usage.
+ * @returns Effect that either runs docker-git clone/open or prints usage.
  *
- * @pure false - uses Console output and spawns commands when cloning
+ * @pure false - uses Console output and spawns commands when running shortcuts
  * @effect Console, CommandExecutor, Path
- * @invariant forall args in Argv: clone(args) -> docker_git_invoked(args)
+ * @invariant forall args in Argv: shortcut(args) -> docker_git_invoked(args)
  * @precondition true
- * @postcondition clone(args) -> docker_git_invoked(args); otherwise usage printed
- * @complexity O(build + clone)
+ * @postcondition shortcut(args) -> docker_git_invoked(args); otherwise usage printed
+ * @complexity O(build + shortcut)
  * @throws Never - all errors are typed in the Effect error channel
  */
 // CHANGE: replace greeting demo with deterministic usage text
@@ -28,32 +28,35 @@ const usageText = [
   "Usage:",
   "  pnpm docker-git",
   "  pnpm clone <repo-url> [ref]",
+  "  pnpm open <repo-url>",
   "  pnpm list",
   "",
   "Notes:",
   "  - docker-git is the interactive TUI.",
-  "  - clone builds + runs docker-git clone for you."
+  "  - clone builds + runs docker-git clone for you.",
+  "  - open builds + runs docker-git open for existing projects."
 ].join("\n")
 
 // PURITY: SHELL
 // EFFECT: Effect<void, never, Console>
 const runHelp = Console.log(usageText)
 
-// CHANGE: route between clone runner and help based on CLI context
-// WHY: allow pnpm run clone <url> while keeping a single entrypoint
-// QUOTE(ТЗ): "pnpm run clone <url>"
+// CHANGE: route between shortcut runners and help based on CLI context
+// WHY: allow pnpm run clone/open <url> while keeping a single entrypoint
+// QUOTE(ТЗ): "Добавить команду open."
 // REF: user-request-2026-01-27
 // SOURCE: n/a
-// FORMAT THEOREM: forall argv: clone(argv) -> docker_git_invoked(argv)
+// FORMAT THEOREM: forall argv: shortcut(argv) -> docker_git_invoked(argv)
 // PURITY: SHELL
 // EFFECT: Effect<void, Error, Console | CommandExecutor | Path>
-// INVARIANT: help is printed when clone is not requested
-// COMPLEXITY: O(build + clone)
+// INVARIANT: help is printed when shortcut is not requested
+// COMPLEXITY: O(build + shortcut)
 const runDockerGit = pipe(
   readCloneRequest,
   Effect.flatMap((request) =>
     Match.value(request).pipe(
       Match.when({ _tag: "Clone" }, ({ args }) => runDockerGitClone(args)),
+      Match.when({ _tag: "Open" }, ({ args }) => runDockerGitOpen(args)),
       Match.when({ _tag: "None" }, () => runHelp),
       Match.exhaustive
     )

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

@@ -75,6 +75,7 @@ export const parseArgs = (args: ReadonlyArray<string>): Either.Either<Command, P
       Match.when("auth", () => parseAuth(rest))
     )
     .pipe(
+      Match.when("open", () => parseAttach(rest)),
       Match.when("apply", () => parseApply(rest)),
       Match.when("state", () => parseState(rest)),
       Match.orElse(() => Either.left(unknownCommandError))

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

@@ -5,6 +5,7 @@ import type { ParseError } from "@effect-template/lib/core/domain"
 export const usageText = `docker-git menu
 docker-git create [--repo-url <url>] [options]
 docker-git clone <url> [options]
+docker-git open [<url>] [options]
 docker-git apply [<url>] [options]
 docker-git mcp-playwright [<url>] [options]
 docker-git attach [<url>] [options]
@@ -22,9 +23,10 @@ Commands:
   menu                Interactive menu (default when no args)
   create, init        Generate docker development environment (repo URL optional)
   clone               Create + run container and clone repo
+  open                Open existing docker-git project workspace
   apply               Apply docker-git config to an existing project/container (current dir by default)
   mcp-playwright      Enable Playwright MCP + Chromium sidecar for an existing project dir
-  attach, tmux        Open tmux workspace for a docker-git project
+  attach, tmux        Alias for open
   panes, terms        List tmux panes for a docker-git project
   scrap               Export/import project scrap (session snapshot + rebuildable deps)
   sessions            List/kill/log container terminal processes
@@ -51,7 +53,7 @@ Options:
   --network-mode <mode>     Compose network mode: shared|project (default: shared)
   --shared-network <name>   Shared Docker network name when network-mode=shared (default: docker-git-shared)
   --out-dir <path>          Output directory (default: <projectsRoot>/<org>/<repo>[/issue-<id>|/pr-<id>])
-  --project-dir <path>      Project directory for attach (default: .)
+  --project-dir <path>      Project directory for open/attach (default: .)
   --archive <path>          Scrap snapshot directory (default: .orch/scrap/session)
   --mode <session>          Scrap mode (default: session)
   --git-token <label>       Token label for clone/create (maps to GITHUB_TOKEN__<LABEL>, example: agiens)

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

@@ -217,6 +217,15 @@ describe("parseArgs", () => {
       expect(command.projectDir).toBe(".docker-git/org/repo/issue-7")
     }))
 
+  it.effect("parses open with GitHub issue url into issue workspace", () =>
+    Effect.sync(() => {
+      const command = parseOrThrow(["open", "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 mcp-playwright command in current directory", () =>
     expectProjectDirRunUpCommand(["mcp-playwright"], "McpPlaywrightUp", ".", true))
 

packages/lib/src/core/clone.ts

@@ -1,5 +1,6 @@
 export type CloneRequest =
   | { readonly _tag: "Clone"; readonly args: ReadonlyArray<string> }
+  | { readonly _tag: "Open"; readonly args: ReadonlyArray<string> }
   | { readonly _tag: "None" }
 
 const emptyRequest: CloneRequest = { _tag: "None" }
@@ -9,32 +10,51 @@ const toCloneRequest = (args: ReadonlyArray<string>): CloneRequest => ({
   args
 })
 
-// CHANGE: resolve a clone request from argv + npm lifecycle metadata
-// WHY: support pnpm run clone <url> without requiring "--"
-// QUOTE(ТЗ): "pnpm run clone <url>"
+const toOpenRequest = (args: ReadonlyArray<string>): CloneRequest => ({
+  _tag: "Open",
+  args
+})
+
+const resolveLifecycleArgs = (
+  argv: ReadonlyArray<string>,
+  command: "clone" | "open"
+): ReadonlyArray<string> => {
+  if (argv.length === 0) {
+    return []
+  }
+  const [first, ...rest] = argv
+  return first === command ? rest : argv
+}
+
+// CHANGE: resolve clone/open shortcut requests from argv + npm lifecycle metadata
+// WHY: support pnpm run clone/open <url> without requiring "--"
+// QUOTE(ТЗ): "Добавить команду open. ... Просто открывает существующий по ссылке"
 // REF: user-request-2026-01-27
 // SOURCE: n/a
 // FORMAT THEOREM: forall a,e: resolve(a,e) -> deterministic
 // PURITY: CORE
 // EFFECT: Effect<CloneRequest, never, never>
-// INVARIANT: clone requested only when argv[0] == "clone" or npmLifecycleEvent == "clone"
+// INVARIANT: command requested only when argv[0] or npmLifecycleEvent is clone/open
 // COMPLEXITY: O(n)
 export const resolveCloneRequest = (
   argv: ReadonlyArray<string>,
   npmLifecycleEvent: string | undefined
 ): CloneRequest => {
   if (npmLifecycleEvent === "clone") {
-    if (argv.length > 0) {
-      const [first, ...rest] = argv
-      return first === "clone" ? toCloneRequest(rest) : toCloneRequest(argv)
-    }
+    return toCloneRequest(resolveLifecycleArgs(argv, "clone"))
+  }
 
-    return toCloneRequest([])
+  if (npmLifecycleEvent === "open") {
+    return toOpenRequest(resolveLifecycleArgs(argv, "open"))
   }
 
   if (argv.length > 0 && argv[0] === "clone") {
     return toCloneRequest(argv.slice(1))
   }
 
+  if (argv.length > 0 && argv[0] === "open") {
+    return toOpenRequest(argv.slice(1))
+  }
+
   return emptyRequest
 }

packages/lib/src/shell/clone.ts

@@ -10,9 +10,9 @@ import { CommandFailedError } from "./errors.js"
 
 const successExitCode = Number(ExitCode(0))
 
-// CHANGE: read clone request from process argv and npm lifecycle metadata
-// WHY: allow pnpm run clone <url> to work without "--"
-// QUOTE(ТЗ): "pnpm run clone <url>"
+// CHANGE: read shortcut requests from process argv and npm lifecycle metadata
+// WHY: allow pnpm run clone/open <url> to work without "--"
+// QUOTE(ТЗ): "Добавить команду open. ... Просто открывает существующий по ссылке"
 // REF: user-request-2026-01-27
 // SOURCE: n/a
 // FORMAT THEOREM: forall env: read(env) -> deterministic(request)
@@ -24,17 +24,8 @@ export const readCloneRequest: Effect.Effect<CloneRequest> = Effect.sync(() =>
   resolveCloneRequest(process.argv.slice(2), process.env["npm_lifecycle_event"])
 )
 
-// CHANGE: run docker-git clone by building and invoking its CLI
-// WHY: reuse docker-git without mutating its codebase
-// QUOTE(ТЗ): "docker git мы никак не изменяем"
-// REF: user-request-2026-01-27
-// SOURCE: n/a
-// FORMAT THEOREM: forall args: build && run(args) -> docker_git_invoked(args)
-// PURITY: SHELL
-// EFFECT: Effect<void, CommandFailedError | PlatformError, CommandExecutor | Path>
-// INVARIANT: build runs before clone command
-// COMPLEXITY: O(build + clone)
-export const runDockerGitClone = (
+const runDockerGitCommand = (
+  commandName: "clone" | "open",
   args: ReadonlyArray<string>
 ): Effect.Effect<
   void,
@@ -47,7 +38,7 @@ export const runDockerGitClone = (
     const appRoot = path.join(workspaceRoot, "packages", "app")
     const dockerGitCli = path.join(appRoot, "dist", "src", "docker-git", "main.js")
     const buildLabel = `pnpm -C ${appRoot} build:docker-git`
-    const cloneLabel = `node ${dockerGitCli} clone`
+    const runLabel = `node ${dockerGitCli} ${commandName}`
 
     yield* _(
       runCommandWithExitCodes(
@@ -58,9 +49,45 @@ export const runDockerGitClone = (
     )
     yield* _(
       runCommandWithExitCodes(
-        { cwd: workspaceRoot, command: "node", args: [dockerGitCli, "clone", ...args] },
+        { cwd: workspaceRoot, command: "node", args: [dockerGitCli, commandName, ...args] },
         [successExitCode],
-        (exitCode) => new CommandFailedError({ command: cloneLabel, exitCode })
+        (exitCode) => new CommandFailedError({ command: runLabel, exitCode })
       )
     )
   })
+
+// CHANGE: run docker-git clone by building and invoking its CLI
+// WHY: reuse docker-git without mutating its codebase
+// QUOTE(ТЗ): "docker git мы никак не изменяем"
+// REF: user-request-2026-01-27
+// SOURCE: n/a
+// FORMAT THEOREM: forall args: build && run(args) -> docker_git_invoked(args)
+// PURITY: SHELL
+// EFFECT: Effect<void, CommandFailedError | PlatformError, CommandExecutor | Path>
+// INVARIANT: build runs before clone command
+// COMPLEXITY: O(build + clone)
+export const runDockerGitClone = (
+  args: ReadonlyArray<string>
+): Effect.Effect<
+  void,
+  CommandFailedError | PlatformError,
+  CommandExecutor.CommandExecutor | Path.Path
+> => runDockerGitCommand("clone", args)
+
+// CHANGE: run docker-git open by building and invoking its CLI
+// WHY: mirror clone shortcut behavior for opening an existing repo workspace
+// QUOTE(ТЗ): "Добавить команду open. ... Просто открывает существующий по ссылке"
+// REF: user-request-2026-02-20-open-command
+// SOURCE: n/a
+// FORMAT THEOREM: forall args: build && run(args) -> docker_git_open_invoked(args)
+// PURITY: SHELL
+// EFFECT: Effect<void, CommandFailedError | PlatformError, CommandExecutor | Path>
+// INVARIANT: build runs before open command
+// COMPLEXITY: O(build + open)
+export const runDockerGitOpen = (
+  args: ReadonlyArray<string>
+): Effect.Effect<
+  void,
+  CommandFailedError | PlatformError,
+  CommandExecutor.CommandExecutor | Path.Path
+> => runDockerGitCommand("open", args)

packages/lib/tests/core/clone.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "@effect/vitest"
+import { Effect } from "effect"
+
+import { resolveCloneRequest } from "../../src/core/clone.js"
+
+describe("resolveCloneRequest", () => {
+  it.effect("parses clone from argv", () =>
+    Effect.sync(() => {
+      expect(resolveCloneRequest(["clone", "https://github.com/org/repo.git"], undefined)).toEqual({
+        _tag: "Clone",
+        args: ["https://github.com/org/repo.git"]
+      })
+    }))
+
+  it.effect("parses open from argv", () =>
+    Effect.sync(() => {
+      expect(resolveCloneRequest(["open", "https://github.com/org/repo/issues/7"], undefined)).toEqual({
+        _tag: "Open",
+        args: ["https://github.com/org/repo/issues/7"]
+      })
+    }))
+
+  it.effect("parses open from npm lifecycle", () =>
+    Effect.sync(() => {
+      expect(resolveCloneRequest(["open", "https://github.com/org/repo.git"], "open")).toEqual({
+        _tag: "Open",
+        args: ["https://github.com/org/repo.git"]
+      })
+    }))
+
+  it.effect("returns none for unrelated argv", () =>
+    Effect.sync(() => {
+      expect(resolveCloneRequest(["list"], undefined)).toEqual({
+        _tag: "None"
+      })
+    }))
+})