update

.github/workflows/cli_go_release.yml

@@ -0,0 +1,284 @@
+name: "CLI: Build Go binaries and platform wheels"
+run-name: "CLI Go release ${{ inputs.version || 'dev' }} by @${{ github.actor }}"
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to build (reads from __init__.py if empty)"
+        required: false
+        type: string
+      publish:
+        description: "Publish wheels to PyPI"
+        required: false
+        type: boolean
+        default: false
+
+  # Also triggered by the main release workflow for libs/cli
+  workflow_call:
+    inputs:
+      version:
+        required: false
+        type: string
+      publish:
+        required: false
+        type: boolean
+
+permissions:
+  contents: read
+
+env:
+  GO_VERSION: "1.23"
+  PYTHON_VERSION: "3.11"
+  WORKING_DIR: "libs/cli"
+
+jobs:
+  # -----------------------------------------------------------------------
+  # Stage 1: Cross-compile Go binaries for all platforms
+  # -----------------------------------------------------------------------
+  build-go:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+            plat: manylinux_2_17_x86_64.manylinux2014_x86_64
+          - goos: linux
+            goarch: arm64
+            plat: manylinux_2_17_aarch64.manylinux2014_aarch64
+          - goos: darwin
+            goarch: amd64
+            plat: macosx_11_0_x86_64
+          - goos: darwin
+            goarch: arm64
+            plat: macosx_11_0_arm64
+          - goos: windows
+            goarch: amd64
+            plat: win_amd64
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ env.GO_VERSION }}
+
+      - name: Determine version
+        id: version
+        working-directory: ${{ env.WORKING_DIR }}
+        run: |
+          if [ -n "${{ inputs.version }}" ]; then
+            echo "version=${{ inputs.version }}" >> "$GITHUB_OUTPUT"
+          else
+            VERSION=$(grep -m 1 '^__version__' langgraph_cli/__init__.py | cut -d '"' -f 2)
+            echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          fi
+          COMMIT=$(git rev-parse --short HEAD)
+          echo "commit=$COMMIT" >> "$GITHUB_OUTPUT"
+
+      - name: Build Go binary
+        working-directory: ${{ env.WORKING_DIR }}
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CGO_ENABLED: "0"
+        run: |
+          EXT=""
+          if [ "${{ matrix.goos }}" = "windows" ]; then EXT=".exe"; fi
+          OUTNAME="langgraph-${{ matrix.goos }}-${{ matrix.goarch }}${EXT}"
+
+          go build \
+            -ldflags "-s -w \
+              -X 'github.com/langchain-ai/langgraph/libs/cli/internal/version.Version=${{ steps.version.outputs.version }}' \
+              -X 'github.com/langchain-ai/langgraph/libs/cli/internal/version.Commit=${{ steps.version.outputs.commit }}' \
+              -X 'github.com/langchain-ai/langgraph/libs/cli/internal/version.Date=$(date -u +%Y-%m-%dT%H:%M:%SZ)'" \
+            -o "$OUTNAME" \
+            cmd/langgraph/main.go
+
+          echo "binary=$OUTNAME" >> "$GITHUB_OUTPUT"
+          echo "Built $OUTNAME ($(stat -c%s "$OUTNAME" 2>/dev/null || stat -f%z "$OUTNAME") bytes)"
+
+      - name: Upload binary artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: go-binary-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: ${{ env.WORKING_DIR }}/langgraph-${{ matrix.goos }}-${{ matrix.goarch }}*
+          retention-days: 7
+
+  # -----------------------------------------------------------------------
+  # Stage 2: Run Go tests
+  # -----------------------------------------------------------------------
+  test-go:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ env.GO_VERSION }}
+      - name: Run tests
+        working-directory: ${{ env.WORKING_DIR }}
+        run: go test -count=1 -race ./...
+
+  # -----------------------------------------------------------------------
+  # Stage 3: Build platform-specific wheels (one per Go target)
+  # -----------------------------------------------------------------------
+  build-wheels:
+    needs: [build-go, test-go]
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+            plat: manylinux_2_17_x86_64.manylinux2014_x86_64
+          - goos: linux
+            goarch: arm64
+            plat: manylinux_2_17_aarch64.manylinux2014_aarch64
+          - goos: darwin
+            goarch: amd64
+            plat: macosx_11_0_x86_64
+          - goos: darwin
+            goarch: arm64
+            plat: macosx_11_0_arm64
+          - goos: windows
+            goarch: amd64
+            plat: win_amd64
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: ./.github/actions/uv_setup
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache-suffix: "cli-wheel"
+          working-directory: ${{ env.WORKING_DIR }}
+
+      - name: Download Go binary
+        uses: actions/download-artifact@v7
+        with:
+          name: go-binary-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: ${{ env.WORKING_DIR }}/
+
+      - name: Build platform wheel
+        working-directory: ${{ env.WORKING_DIR }}
+        env:
+          LANGGRAPH_GO_BINARY: langgraph-${{ matrix.goos }}-${{ matrix.goarch }}${{ matrix.goos == 'windows' && '.exe' || '' }}
+          LANGGRAPH_WHEEL_PLAT: ${{ matrix.plat }}
+        run: |
+          chmod +x "$LANGGRAPH_GO_BINARY"
+          uv build --wheel
+          echo "Built wheel:"
+          ls -lh dist/*.whl
+
+      - name: Upload wheel
+        uses: actions/upload-artifact@v7
+        with:
+          name: wheel-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: ${{ env.WORKING_DIR }}/dist/*.whl
+          retention-days: 7
+
+  # -----------------------------------------------------------------------
+  # Stage 4: Build pure-Python fallback wheel (no Go binary)
+  # -----------------------------------------------------------------------
+  build-sdist:
+    needs: [test-go]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: ./.github/actions/uv_setup
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache-suffix: "cli-sdist"
+          working-directory: ${{ env.WORKING_DIR }}
+
+      - name: Build sdist and fallback wheel
+        working-directory: ${{ env.WORKING_DIR }}
+        run: |
+          uv build
+          echo "Built:"
+          ls -lh dist/
+
+      - name: Upload sdist and fallback wheel
+        uses: actions/upload-artifact@v7
+        with:
+          name: sdist-and-fallback
+          path: ${{ env.WORKING_DIR }}/dist/
+          retention-days: 7
+
+  # -----------------------------------------------------------------------
+  # Stage 5: Validate wheels install correctly
+  # -----------------------------------------------------------------------
+  validate-wheels:
+    needs: [build-wheels, build-sdist]
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Download all wheels
+        uses: actions/download-artifact@v7
+        with:
+          pattern: wheel-*
+          path: wheels/
+          merge-multiple: true
+
+      - name: Download fallback
+        uses: actions/download-artifact@v7
+        with:
+          name: sdist-and-fallback
+          path: wheels/
+
+      - name: Install and test
+        shell: bash
+        run: |
+          pip install wheels/*.whl 2>/dev/null || pip install wheels/langgraph_cli-*.tar.gz
+          langgraph --help
+          langgraph --version
+          echo "Wheel installs and runs correctly on ${{ matrix.os }} / Python ${{ matrix.python-version }}"
+
+  # -----------------------------------------------------------------------
+  # Stage 6: Publish to PyPI (only when publish=true)
+  # -----------------------------------------------------------------------
+  publish:
+    if: ${{ inputs.publish }}
+    needs: [validate-wheels]
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # required for trusted publishing
+    steps:
+      - name: Download platform wheels
+        uses: actions/download-artifact@v7
+        with:
+          pattern: wheel-*
+          path: dist/
+          merge-multiple: true
+
+      - name: Download sdist
+        uses: actions/download-artifact@v7
+        with:
+          name: sdist-and-fallback
+          path: dist/
+
+      - name: List all artifacts
+        run: ls -lh dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true

libs/cli/.gitignore

@@ -1 +1,3 @@
 .langgraph_api/
+# Go cross-compiled binaries (built at release time, bundled into wheels)
+langgraph_cli/bin/

libs/cli/Makefile

@@ -1,5 +1,6 @@
 .PHONY: test lint type format test-integration update-schema bump-version
 .PHONY: test-go lint-go format-go
+.PHONY: build-go build-go-all clean-go-bin
 
 ######################
 # TESTING AND COVERAGE
@@ -47,6 +48,66 @@ format format_diff: format-go
 format-go:
 	[ -z "$(GO_FILES)" ] || gofmt -w $(GO_FILES)
 
+######################
+# GO BINARY CROSS-COMPILATION
+######################
+
+GO_MODULE=github.com/langchain-ai/langgraph/libs/cli
+GO_BINARY=cmd/langgraph/main.go
+GO_VERSION_PKG=$(GO_MODULE)/internal/version
+GO_BIN_DIR=langgraph_cli/bin
+GO_VERSION=$(shell grep -m 1 '^__version__' langgraph_cli/__init__.py | cut -d '"' -f 2)
+GO_COMMIT=$(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+GO_DATE=$(shell date -u +%Y-%m-%dT%H:%M:%SZ)
+GO_LDFLAGS=-s -w \
+  -X '$(GO_VERSION_PKG).Version=$(GO_VERSION)' \
+  -X '$(GO_VERSION_PKG).Commit=$(GO_COMMIT)' \
+  -X '$(GO_VERSION_PKG).Date=$(GO_DATE)'
+
+# Platform matrix — matches orjson support as proxy for practical CLI targets.
+GO_PLATFORMS = \
+  linux/amd64 \
+  linux/arm64 \
+  darwin/amd64 \
+  darwin/arm64 \
+  windows/amd64
+
+# Build for the current platform (development).
+build-go:
+	@mkdir -p $(GO_BIN_DIR)
+	go build -ldflags "$(GO_LDFLAGS)" -o $(GO_BIN_DIR)/langgraph $(GO_BINARY)
+	@echo "Built $(GO_BIN_DIR)/langgraph"
+
+# Build for a single target: make build-go-target GOOS=linux GOARCH=amd64
+build-go-target:
+	$(eval EXT=$(if $(filter windows,$(GOOS)),.exe,))
+	@mkdir -p $(GO_BIN_DIR)
+	GOOS=$(GOOS) GOARCH=$(GOARCH) CGO_ENABLED=0 \
+		go build -ldflags "$(GO_LDFLAGS)" \
+		-o $(GO_BIN_DIR)/langgraph-$(GOOS)-$(GOARCH)$(EXT) $(GO_BINARY)
+	@echo "Built $(GO_BIN_DIR)/langgraph-$(GOOS)-$(GOARCH)$(EXT)"
+
+# Build for all platforms.
+build-go-all:
+	@mkdir -p $(GO_BIN_DIR)
+	@for platform in $(GO_PLATFORMS); do \
+		os=$${platform%/*}; arch=$${platform#*/}; \
+		ext=""; \
+		if [ "$$os" = "windows" ]; then ext=".exe"; fi; \
+		echo "Building $$os/$$arch..."; \
+		GOOS=$$os GOARCH=$$arch CGO_ENABLED=0 \
+			go build -ldflags "$(GO_LDFLAGS)" \
+			-o $(GO_BIN_DIR)/langgraph-$$os-$$arch$$ext $(GO_BINARY) || exit 1; \
+	done
+	@echo "All platforms built in $(GO_BIN_DIR)/"
+
+clean-go-bin:
+	rm -rf $(GO_BIN_DIR)
+
+######################
+# SCHEMA AND VERSIONING
+######################
+
 update-schema:
 	uv run python generate_schema.py
 

libs/cli/hatch_build.py

@@ -0,0 +1,56 @@
+"""Hatch build hook that bundles the platform-specific Go binary into the wheel.
+
+Usage:
+  1. Cross-compile: make build-go-target GOOS=linux GOARCH=amd64
+  2. Set LANGGRAPH_GO_BINARY to the built binary path
+  3. Build wheel: uv build --wheel
+
+The hook copies the binary into langgraph_cli/bin/ so the entrypoint can find it.
+If LANGGRAPH_GO_BINARY is not set, the wheel is built without a binary (pure Python
+fallback — fine for development and the legacy code path).
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class GoBinaryBuildHook(BuildHookInterface):
+    PLUGIN_NAME = "go-binary"
+
+    def initialize(self, version: str, build_data: dict) -> None:
+        binary_path = os.environ.get("LANGGRAPH_GO_BINARY")
+        if not binary_path:
+            return
+
+        source = Path(binary_path)
+        if not source.is_file():
+            msg = f"LANGGRAPH_GO_BINARY points to missing file: {source}"
+            raise FileNotFoundError(msg)
+
+        bin_dir = Path("langgraph_cli/bin")
+        bin_dir.mkdir(parents=True, exist_ok=True)
+
+        # Determine output name (langgraph or langgraph.exe)
+        dest_name = "langgraph.exe" if source.suffix == ".exe" else "langgraph"
+        dest = bin_dir / dest_name
+
+        shutil.copy2(str(source), str(dest))
+        # Ensure executable permission
+        dest.chmod(dest.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+        # Tell hatch to include the binary in the wheel
+        build_data["shared_data"] = {}
+        build_data["force_include"] = {
+            str(dest): f"langgraph_cli/bin/{dest_name}",
+        }
+
+        # Set the platform tag so pip installs the right wheel
+        platform_tag = os.environ.get("LANGGRAPH_WHEEL_PLAT")
+        if platform_tag:
+            build_data["tag"] = f"py3-none-{platform_tag}"

libs/cli/internal/config/docker.go

@@ -765,15 +765,16 @@ func PythonConfigToDocker(
 	escapeVariables bool,
 ) (string, map[string]string, error) {
 	sourceKind := getSourceKind(config)
-	if sourceKind == "uv" {
-		return "", nil, fmt.Errorf("UV lock mode not yet supported in Go CLI")
-	}
 
 	buildToolsToUninstall, err := GetBuildToolsToUninstall(config)
 	if err != nil {
 		return "", nil, err
 	}
 
+	if sourceKind == "uv" {
+		return PythonConfigToDockerUVLock(configPath, config, baseImage, apiVersion, buildToolsToUninstall)
+	}
+
 	pipInstaller, _ := config["pip_installer"].(string)
 	if pipInstaller == "" {
 		pipInstaller = "auto"

libs/cli/internal/config/uvlock_test.go

@@ -0,0 +1,804 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// ---------------------------------------------------------------------------
+// Helper: write a uv-lock workspace fixture
+// ---------------------------------------------------------------------------
+
+type workspaceOpts struct {
+	// Relative directory (within project_root) that holds langgraph.json.
+	// Default: "deploy/agent"
+	configRelativeDir string
+	// Extra TOML appended to the root pyproject.toml (e.g. [tool.uv.sources]).
+	rootSources string
+	// Extra TOML appended to the agent pyproject.toml (e.g. [tool.uv.sources]).
+	agentSources string
+	// Extra TOML appended to the shared lib pyproject.toml (e.g. [tool.uv] section).
+	sharedUvConfig string
+	// Custom agent dependencies list.  When nil the default is used.
+	agentDependencies []string
+	// Additional files to create: relative-path (from project_root) -> content.
+	extraFiles map[string]string
+}
+
+// writeUvLockWorkspace creates the standard multi-package uv workspace used
+// by the Python test_config_to_docker_uv_lock* test suite and returns
+// (projectRoot, configPath).
+//
+// Layout:
+//
+//	workspace/
+//	  pyproject.toml          [project] name="workspace-root" + [tool.uv.workspace]
+//	  uv.lock
+//	  apps/agent/             package "agent"
+//	    pyproject.toml
+//	    src/agent/graph.py
+//	  libs/shared/            package "shared"
+//	    pyproject.toml
+//	    src/shared/auth.py
+//	  libs/extra/             package "extra" (not a dep of agent)
+//	    pyproject.toml
+//	    src/extra/graph.py
+//	  deploy/agent/           config directory (configRelativeDir)
+//	    langgraph.json
+func writeUvLockWorkspace(t *testing.T, opts workspaceOpts) (string, string) {
+	t.Helper()
+	base := t.TempDir()
+	projectRoot := filepath.Join(base, "workspace")
+
+	configRelDir := opts.configRelativeDir
+	if configRelDir == "" {
+		configRelDir = "deploy/agent"
+	}
+
+	configDir := filepath.Join(projectRoot, configRelDir)
+	sharedDir := filepath.Join(projectRoot, "libs", "shared")
+	extraDir := filepath.Join(projectRoot, "libs", "extra")
+	deployDir := filepath.Join(projectRoot, "deploy", "agent")
+
+	for _, d := range []string{configDir, sharedDir, extraDir, deployDir} {
+		if err := os.MkdirAll(d, 0o755); err != nil {
+			t.Fatalf("MkdirAll(%q): %v", d, err)
+		}
+	}
+
+	// -- root pyproject.toml -------------------------------------------------
+	rootSources := opts.rootSources
+	writeFile(t, filepath.Join(projectRoot, "pyproject.toml"),
+		"[project]\n"+
+			"name = \"workspace-root\"\n"+
+			"version = \"0.1.0\"\n"+
+			"\n"+
+			"[tool.uv.workspace]\n"+
+			"members = [\"apps/*\", \"libs/*\"]\n"+
+			"\n"+
+			rootSources+"\n"+
+			"\n"+
+			"[build-system]\n"+
+			"requires = [\"setuptools>=61\"]\n"+
+			"build-backend = \"setuptools.build_meta\"\n")
+
+	// -- uv.lock -------------------------------------------------------------
+	writeFile(t, filepath.Join(projectRoot, "uv.lock"), "# uv lock file\n")
+
+	// -- agent pyproject.toml ------------------------------------------------
+	agentDir := filepath.Join(projectRoot, "apps", "agent")
+	if err := os.MkdirAll(agentDir, 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+
+	agentDeps := opts.agentDependencies
+	if agentDeps == nil {
+		agentDeps = []string{"shared", "httpx>=0.28"}
+	}
+	depsList := "[\"" + strings.Join(agentDeps, "\", \"") + "\"]"
+
+	agentSources := opts.agentSources
+	writeFile(t, filepath.Join(agentDir, "pyproject.toml"),
+		"[project]\n"+
+			"name = \"agent\"\n"+
+			"version = \"0.1.0\"\n"+
+			"dependencies = "+depsList+"\n"+
+			"\n"+
+			agentSources+"\n"+
+			"\n"+
+			"[build-system]\n"+
+			"requires = [\"setuptools>=61\"]\n"+
+			"build-backend = \"setuptools.build_meta\"\n")
+
+	// -- shared pyproject.toml -----------------------------------------------
+	sharedUvConfig := opts.sharedUvConfig
+	writeFile(t, filepath.Join(sharedDir, "pyproject.toml"),
+		"[project]\n"+
+			"name = \"shared\"\n"+
+			"version = \"0.1.0\"\n"+
+			"dependencies = [\"anyio>=4\"]\n"+
+			"\n"+
+			sharedUvConfig+"\n"+
+			"\n"+
+			"[build-system]\n"+
+			"requires = [\"setuptools>=61\"]\n"+
+			"build-backend = \"setuptools.build_meta\"\n")
+
+	// -- extra pyproject.toml ------------------------------------------------
+	writeFile(t, filepath.Join(extraDir, "pyproject.toml"),
+		"[project]\n"+
+			"name = \"extra\"\n"+
+			"version = \"0.1.0\"\n"+
+			"\n"+
+			"[build-system]\n"+
+			"requires = [\"setuptools>=61\"]\n"+
+			"build-backend = \"setuptools.build_meta\"\n")
+
+	// -- source files --------------------------------------------------------
+	writeFile(t, filepath.Join(agentDir, "src", "agent", "graph.py"), "")
+	writeFile(t, filepath.Join(sharedDir, "src", "shared", "auth.py"), "")
+	writeFile(t, filepath.Join(extraDir, "src", "extra", "graph.py"), "")
+
+	// -- config file ---------------------------------------------------------
+	configPath := filepath.Join(deployDir, "langgraph.json")
+	writeFile(t, configPath, "{}\n")
+
+	// If configRelativeDir is non-default, also place langgraph.json there.
+	if configRelDir != "deploy/agent" {
+		altConfigPath := filepath.Join(configDir, "langgraph.json")
+		writeFile(t, altConfigPath, "{}\n")
+		configPath = altConfigPath
+	}
+
+	// -- extra files ---------------------------------------------------------
+	for relPath, content := range opts.extraFiles {
+		writeFile(t, filepath.Join(projectRoot, relPath), content)
+	}
+
+	return projectRoot, configPath
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+func TestUvLockBasic(t *testing.T) {
+	_, configPath := writeUvLockWorkspace(t, workspaceOpts{
+		agentSources: "[tool.uv.sources]\nshared = { workspace = true }",
+	})
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			"agent": "../../apps/agent/src/agent/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+		"auth":   map[string]any{"path": "../../libs/shared/src/shared/auth.py:create_auth"},
+	})
+
+	docker, contexts, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err != nil {
+		t.Fatalf("ConfigToDocker: %v", err)
+	}
+
+	// Core commands.
+	assertContains(t, docker, "uv pip install --system")
+	assertContains(t, docker,
+		"uv export --package 'agent' --frozen --no-hashes --no-emit-project --no-emit-workspace")
+
+	// Copy project metadata for uv export.
+	assertContains(t, docker,
+		"COPY --from=uv-workspace-root pyproject.toml /tmp/uv_export/project/pyproject.toml")
+	assertContains(t, docker,
+		"COPY --from=uv-workspace-root uv.lock /tmp/uv_export/project/uv.lock")
+
+	// Additional build contexts.
+	if _, ok := contexts["uv-workspace-root"]; !ok {
+		t.Fatal("expected 'uv-workspace-root' in additional contexts")
+	}
+
+	// Workspace packages copied.
+	assertContains(t, docker,
+		"COPY --from=uv-workspace-root apps/agent /deps/workspace/apps/agent")
+	assertContains(t, docker,
+		"COPY --from=uv-workspace-root libs/shared /deps/workspace/libs/shared")
+	// Unrelated member NOT copied.
+	assertNotContains(t, docker,
+		"libs/extra /deps/workspace/libs/extra")
+
+	// Install order: shared before agent.
+	assertContains(t, docker, "WORKDIR /deps/workspace/libs/shared")
+	assertContains(t, docker, "WORKDIR /deps/workspace/apps/agent")
+	sharedInstall := "uv pip install --system --no-cache-dir -c /api/constraints.txt --no-deps -e ."
+	assertContains(t, docker, sharedInstall)
+
+	// Ordering: shared COPY < shared WORKDIR < agent COPY < agent WORKDIR.
+	sharedCopy := "COPY --from=uv-workspace-root libs/shared /deps/workspace/libs/shared"
+	sharedWD := "WORKDIR /deps/workspace/libs/shared"
+	agentCopy := "COPY --from=uv-workspace-root apps/agent /deps/workspace/apps/agent"
+	agentWD := "WORKDIR /deps/workspace/apps/agent"
+	if strings.Index(docker, sharedCopy) >= strings.Index(docker, sharedWD) {
+		t.Error("shared COPY should appear before shared WORKDIR")
+	}
+	if strings.Index(docker, sharedWD) >= strings.Index(docker, agentCopy) {
+		t.Error("shared WORKDIR should appear before agent COPY")
+	}
+	if strings.Index(docker, sharedWD) >= strings.Index(docker, agentWD) {
+		t.Error("shared WORKDIR should appear before agent WORKDIR")
+	}
+
+	// No legacy dep-loop patterns.
+	assertNotContains(t, docker, "for dep in /deps/*")
+	assertNotContains(t, docker, "# -- Installing workspace packages --")
+	assertContains(t, docker, "WORKDIR /tmp/uv_export/project")
+	assertNotContains(t, docker, "RUN cd ")
+
+	// Rewritten paths in env vars (Go JSON uses compact format without spaces).
+	assertContains(t, docker,
+		`"/deps/workspace/libs/shared/src/shared/auth.py:create_auth"`)
+	assertContains(t, docker,
+		`"/deps/workspace/apps/agent/src/agent/graph.py:graph"`)
+
+	// Cleanup.
+	assertContains(t, docker, "rm /usr/bin/uv /usr/bin/uvx")
+}
+
+func TestUvLockHonorsRootWorkspaceSources(t *testing.T) {
+	_, configPath := writeUvLockWorkspace(t, workspaceOpts{
+		rootSources: "[tool.uv.sources]\nshared = { workspace = true }",
+	})
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			"agent": "../../apps/agent/src/agent/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+		"auth":   map[string]any{"path": "../../libs/shared/src/shared/auth.py:create_auth"},
+	})
+
+	docker, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err != nil {
+		t.Fatalf("ConfigToDocker: %v", err)
+	}
+
+	assertContains(t, docker,
+		"COPY --from=uv-workspace-root libs/shared /deps/workspace/libs/shared")
+	assertContains(t, docker,
+		`"/deps/workspace/libs/shared/src/shared/auth.py:create_auth"`)
+}
+
+func TestUvLockIgnoresUnrelatedWorkspacePackageSources(t *testing.T) {
+	projectRoot, configPath := writeUvLockWorkspace(t, workspaceOpts{
+		agentSources: "[tool.uv.sources]\nshared = { workspace = true }",
+	})
+
+	// Add badlib with [tool.uv.sources] pointing outside (an unrelated member).
+	badlibDir := filepath.Join(projectRoot, "libs", "badlib")
+	writeFile(t, filepath.Join(badlibDir, "pyproject.toml"),
+		"[project]\n"+
+			"name = \"badlib\"\n"+
+			"version = \"0.1.0\"\n"+
+			"\n"+
+			"[tool.uv.sources]\n"+
+			"outside = { path = \"../outside\" }\n"+
+			"\n"+
+			"[build-system]\n"+
+			"requires = [\"setuptools>=61\"]\n"+
+			"build-backend = \"setuptools.build_meta\"\n")
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			"agent": "../../apps/agent/src/agent/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+		"auth":   map[string]any{"path": "../../libs/shared/src/shared/auth.py:create_auth"},
+	})
+
+	docker, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err != nil {
+		t.Fatalf("ConfigToDocker: %v", err)
+	}
+
+	assertContains(t, docker,
+		"COPY --from=uv-workspace-root libs/shared /deps/workspace/libs/shared")
+	assertNotContains(t, docker,
+		"COPY --from=uv-workspace-root libs/badlib /deps/workspace/libs/badlib")
+}
+
+func TestUvLockIgnoresUnrelatedRootSources(t *testing.T) {
+	_, configPath := writeUvLockWorkspace(t, workspaceOpts{
+		rootSources: "[tool.uv.sources]\nshared = { workspace = true }\nunused = { path = \"libs/extra\", editable = true }",
+	})
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			"agent": "../../apps/agent/src/agent/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+		"auth":   map[string]any{"path": "../../libs/shared/src/shared/auth.py:create_auth"},
+	})
+
+	docker, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err != nil {
+		t.Fatalf("ConfigToDocker: %v", err)
+	}
+
+	assertContains(t, docker,
+		"COPY --from=uv-workspace-root libs/shared /deps/workspace/libs/shared")
+	assertNotContains(t, docker,
+		"COPY --from=uv-workspace-root libs/extra /deps/workspace/libs/extra")
+}
+
+func TestUvLockValidatesRootPathSourcesRelativeToProjectRoot(t *testing.T) {
+	projectRoot, configPath := writeUvLockWorkspace(t, workspaceOpts{
+		rootSources: "[tool.uv.sources]\nshared = { path = \"../outside\", editable = true }",
+	})
+
+	// Create the outside directory the source points to.
+	outsideDir := filepath.Join(filepath.Dir(projectRoot), "outside")
+	writeFile(t, filepath.Join(outsideDir, "pyproject.toml"),
+		"[project]\n"+
+			"name = \"shared\"\n"+
+			"version = \"0.1.0\"\n")
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			"agent": "../../apps/agent/src/agent/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+	})
+
+	_, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err == nil {
+		t.Fatal("expected error for path outside project_root")
+	}
+	assertContains(t, err.Error(), "outside project_root")
+}
+
+func TestUvLockRequiresExplicitWorkspaceSources(t *testing.T) {
+	// No agent_sources or root_sources => shared is NOT a workspace dep.
+	_, configPath := writeUvLockWorkspace(t, workspaceOpts{})
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			"agent": "../../apps/agent/src/agent/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+		"auth":   map[string]any{"path": "../../libs/shared/src/shared/auth.py:create_auth"},
+	})
+
+	_, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err == nil {
+		t.Fatal("expected error because shared is not an explicit workspace source")
+	}
+	assertContains(t, err.Error(), "not inside the target package 'agent'")
+}
+
+func TestUvLockAcceptsPathWorkspaceSources(t *testing.T) {
+	_, configPath := writeUvLockWorkspace(t, workspaceOpts{
+		agentSources: "[tool.uv.sources]\nshared = { path = \"../../libs/shared\", editable = true }",
+	})
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			"agent": "../../apps/agent/src/agent/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+	})
+
+	docker, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err != nil {
+		t.Fatalf("ConfigToDocker: %v", err)
+	}
+
+	assertContains(t, docker,
+		"COPY --from=uv-workspace-root libs/shared /deps/workspace/libs/shared")
+}
+
+func TestUvLockRejectsPackageFalseWorkspaceDependency(t *testing.T) {
+	_, configPath := writeUvLockWorkspace(t, workspaceOpts{
+		agentSources:   "[tool.uv.sources]\nshared = { workspace = true }",
+		sharedUvConfig: "[tool.uv]\npackage = false",
+	})
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			"agent": "../../apps/agent/src/agent/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+	})
+
+	_, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err == nil {
+		t.Fatal("expected error for package = false workspace dependency")
+	}
+	assertContains(t, err.Error(), "tool.uv.package = false")
+}
+
+func TestUvLockAcceptsRootPathWorkspaceSources(t *testing.T) {
+	_, configPath := writeUvLockWorkspace(t, workspaceOpts{
+		rootSources: "[tool.uv.sources]\nshared = { path = \"libs/shared\", editable = true }",
+	})
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			"agent": "../../apps/agent/src/agent/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+		"auth":   map[string]any{"path": "../../libs/shared/src/shared/auth.py:create_auth"},
+	})
+
+	docker, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err != nil {
+		t.Fatalf("ConfigToDocker: %v", err)
+	}
+
+	assertContains(t, docker,
+		"COPY --from=uv-workspace-root libs/shared /deps/workspace/libs/shared")
+	assertContains(t, docker,
+		`"/deps/workspace/libs/shared/src/shared/auth.py:create_auth"`)
+}
+
+func TestUvLockRejectsMismatchedPathWorkspaceSources(t *testing.T) {
+	// agent sources point to libs/extra with the name "shared" -> mismatch.
+	_, configPath := writeUvLockWorkspace(t, workspaceOpts{
+		agentSources: "[tool.uv.sources]\nshared = { path = \"../../libs/extra\", editable = true }",
+	})
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			"agent": "../../apps/agent/src/agent/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+	})
+
+	_, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err == nil {
+		t.Fatal("expected error for mismatched path workspace sources")
+	}
+	assertContains(t, err.Error(), "dependency name and the workspace package name must match")
+}
+
+func TestUvLockDetectsJsPmFromTargetPackageRoot(t *testing.T) {
+	projectRoot, configPath := writeUvLockWorkspace(t, workspaceOpts{
+		agentSources: "[tool.uv.sources]\nshared = { workspace = true }",
+	})
+
+	agentDir := filepath.Join(projectRoot, "apps", "agent")
+	writeFile(t, filepath.Join(agentDir, "package.json"), "{\"packageManager\":\"pnpm@9.0.0\"}\n")
+	writeFile(t, filepath.Join(agentDir, "pnpm-lock.yaml"), "lockfileVersion: 9.0\n")
+	writeFile(t, filepath.Join(agentDir, "ui.tsx"), "export const ui = null;\n")
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			"agent": "../../apps/agent/src/agent/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+		"ui":     map[string]any{"agent": "../../apps/agent/ui.tsx"},
+	})
+
+	docker, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err != nil {
+		t.Fatalf("ConfigToDocker: %v", err)
+	}
+
+	assertContains(t, docker, "WORKDIR /deps/workspace/apps/agent")
+	assertContains(t, docker,
+		"RUN pnpm i --frozen-lockfile && tsx /api/langgraph_api/js/build.mts")
+	assertContains(t, docker, `/deps/workspace/apps/agent/ui.tsx`)
+}
+
+func TestUvLockUsesWorkdirForJsInstallWithSpecialChars(t *testing.T) {
+	projectRoot, _ := writeUvLockWorkspace(t, workspaceOpts{
+		configRelativeDir: "apps/agent;echo pwned",
+	})
+
+	// The custom configRelativeDir creates its own langgraph.json.
+	// We need to place the agent pyproject.toml at this directory.
+	agentDir := filepath.Join(projectRoot, "apps", "agent;echo pwned")
+	writeFile(t, filepath.Join(agentDir, "package.json"), "{\"packageManager\":\"pnpm@9.0.0\"}\n")
+	writeFile(t, filepath.Join(agentDir, "pnpm-lock.yaml"), "lockfileVersion: 9.0\n")
+	writeFile(t, filepath.Join(agentDir, "ui.tsx"), "export const ui = null;\n")
+	writeFile(t, filepath.Join(agentDir, "pyproject.toml"),
+		"[project]\n"+
+			"name = \"agent\"\n"+
+			"version = \"0.1.0\"\n"+
+			"dependencies = [\"shared\", \"httpx>=0.28\"]\n"+
+			"\n"+
+			"[build-system]\n"+
+			"requires = [\"setuptools>=61\"]\n"+
+			"build-backend = \"setuptools.build_meta\"\n")
+	writeFile(t, filepath.Join(agentDir, "src", "agent", "graph.py"), "")
+
+	// Remove the default apps/agent so there's no duplicate package name.
+	if err := os.RemoveAll(filepath.Join(projectRoot, "apps", "agent")); err != nil {
+		t.Fatal(err)
+	}
+
+	// Update workspace members to include the special-char directory.
+	writeFile(t, filepath.Join(projectRoot, "pyproject.toml"),
+		"[project]\n"+
+			"name = \"workspace-root\"\n"+
+			"version = \"0.1.0\"\n"+
+			"\n"+
+			"[tool.uv.workspace]\n"+
+			"members = [\"apps/*\", \"libs/*\"]\n"+
+			"\n"+
+			"[build-system]\n"+
+			"requires = [\"setuptools>=61\"]\n"+
+			"build-backend = \"setuptools.build_meta\"\n")
+
+	configPath := filepath.Join(agentDir, "langgraph.json")
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			"agent": "./src/agent/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+		"ui":     map[string]any{"agent": "./ui.tsx"},
+	})
+
+	docker, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err != nil {
+		t.Fatalf("ConfigToDocker: %v", err)
+	}
+
+	assertContains(t, docker, "WORKDIR /deps/workspace/apps/agent;echo pwned")
+	assertContains(t, docker,
+		"RUN pnpm i --frozen-lockfile && tsx /api/langgraph_api/js/build.mts")
+	assertNotContains(t, docker, "RUN cd /deps/workspace/apps/agent;echo pwned")
+}
+
+func TestUvLockSupportsSingleUvProjectRoot(t *testing.T) {
+	base := t.TempDir()
+	projectRoot := filepath.Join(base, "single")
+	if err := os.MkdirAll(projectRoot, 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	writeFile(t, filepath.Join(projectRoot, "uv.lock"), "# uv lock file\n")
+	writeFile(t, filepath.Join(projectRoot, "pyproject.toml"),
+		"[project]\n"+
+			"name = \"single-app\"\n"+
+			"version = \"0.1.0\"\n"+
+			"dependencies = [\"httpx>=0.28\"]\n"+
+			"\n"+
+			"[build-system]\n"+
+			"requires = [\"setuptools>=61\"]\n"+
+			"build-backend = \"setuptools.build_meta\"\n")
+	configPath := filepath.Join(projectRoot, "langgraph.json")
+	writeFile(t, configPath, "{}\n")
+	writeFile(t, filepath.Join(projectRoot, "src", "agent.py"), "graph = object()\n")
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs":         map[string]any{"agent": "./src/agent.py:graph"},
+		"source":         map[string]any{"kind": "uv"},
+	})
+
+	docker, contexts, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err != nil {
+		t.Fatalf("ConfigToDocker: %v", err)
+	}
+
+	assertContains(t, docker,
+		"uv export --package 'single-app' --frozen --no-hashes --no-emit-project --no-emit-workspace")
+	assertContains(t, docker, `"/deps/workspace/src/agent.py:graph"`)
+	if len(contexts) != 0 {
+		t.Fatalf("expected no additional contexts for single-project root, got %d: %v",
+			len(contexts), contexts)
+	}
+}
+
+func TestUvLockRejectsInvalidSourcePackageType(t *testing.T) {
+	_, configPath := writeUvLockWorkspace(t, workspaceOpts{})
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			"agent": "../../apps/agent/src/agent/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+	})
+	// Override the validated source.package to an integer.
+	cfg["source"].(map[string]any)["package"] = 123
+
+	_, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err == nil {
+		t.Fatal("expected error for non-string source.package")
+	}
+	assertContains(t, err.Error(), "`source.package` must be a non-empty string")
+}
+
+func TestUvLockRejectsPathsOutsideTargetClosure(t *testing.T) {
+	_, configPath := writeUvLockWorkspace(t, workspaceOpts{
+		agentSources: "[tool.uv.sources]\nshared = { workspace = true }",
+	})
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			// Graph path points into libs/extra which is NOT a dependency of agent.
+			"agent": "../../libs/extra/src/extra/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+	})
+
+	_, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err == nil {
+		t.Fatal("expected error for graph path outside target closure")
+	}
+	assertContains(t, err.Error(), "not inside the target package 'agent'")
+}
+
+func TestUvLockRejectsUnrelatedMemberWhenRootInClosure(t *testing.T) {
+	_, configPath := writeUvLockWorkspace(t, workspaceOpts{
+		agentDependencies: []string{"workspace-root", "shared", "httpx>=0.28"},
+		rootSources:       "[tool.uv.sources]\nshared = { workspace = true }\nworkspace-root = { workspace = true }",
+		agentSources:      "[tool.uv.sources]\nshared = { workspace = true }\nworkspace-root = { workspace = true }",
+	})
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			// extra is a workspace member but NOT a dependency of agent.
+			"agent": "../../libs/extra/src/extra/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+	})
+
+	_, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err == nil {
+		t.Fatal("expected error for unrelated member when root is in closure")
+	}
+	assertContains(t, err.Error(), "not inside the target package 'agent'")
+}
+
+func TestUvLockRootPackageCopySkipsUnrelatedMembers(t *testing.T) {
+	projectRoot, configPath := writeUvLockWorkspace(t, workspaceOpts{
+		agentDependencies: []string{"workspace-root", "shared", "httpx>=0.28"},
+		rootSources:       "[tool.uv.sources]\nshared = { workspace = true }\nworkspace-root = { workspace = true }",
+		agentSources:      "[tool.uv.sources]\nshared = { workspace = true }\nworkspace-root = { workspace = true }",
+	})
+
+	// Add files in the workspace root package itself.
+	writeFile(t, filepath.Join(projectRoot, "src", "workspace_root", "__init__.py"), "__all__ = []\n")
+	writeFile(t, filepath.Join(projectRoot, "README.md"), "workspace root package\n")
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs": map[string]any{
+			"agent": "../../apps/agent/src/agent/graph.py:graph",
+		},
+		"source": map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+	})
+
+	docker, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err != nil {
+		t.Fatalf("ConfigToDocker: %v", err)
+	}
+
+	// Should NOT do a blanket COPY of the whole workspace root.
+	assertNotContains(t, docker, "COPY --from=uv-workspace-root . /deps/workspace")
+	// Should copy specific entries.
+	assertContains(t, docker, "COPY --from=uv-workspace-root src /deps/workspace/src")
+	assertContains(t, docker, "COPY --from=uv-workspace-root README.md /deps/workspace/README.md")
+	// Should NOT copy unrelated member dirs.
+	assertNotContains(t, docker,
+		"COPY --from=uv-workspace-root libs/extra /deps/workspace/libs/extra")
+	// Should install workspace root from /deps/workspace.
+	assertContains(t, docker, "WORKDIR /deps/workspace")
+	assertContains(t, docker,
+		"uv pip install --system --no-cache-dir -c /api/constraints.txt --no-deps -e .")
+}
+
+func TestUvLockMissingLockfile(t *testing.T) {
+	projectRoot, configPath := writeUvLockWorkspace(t, workspaceOpts{})
+
+	// Remove uv.lock.
+	if err := os.Remove(filepath.Join(projectRoot, "uv.lock")); err != nil {
+		t.Fatal(err)
+	}
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs":         map[string]any{"agent": "../../apps/agent/src/agent/graph.py:graph"},
+		"source":         map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+	})
+
+	_, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err == nil {
+		t.Fatal("expected error for missing uv.lock")
+	}
+	assertContains(t, err.Error(), "No uv.lock found")
+}
+
+func TestUvLockMissingPyproject(t *testing.T) {
+	projectRoot, configPath := writeUvLockWorkspace(t, workspaceOpts{})
+
+	// Remove root pyproject.toml.
+	if err := os.Remove(filepath.Join(projectRoot, "pyproject.toml")); err != nil {
+		t.Fatal(err)
+	}
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs":         map[string]any{"agent": "../../apps/agent/src/agent/graph.py:graph"},
+		"source":         map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+	})
+
+	_, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.47",
+	})
+	if err == nil {
+		t.Fatal("expected error for missing pyproject.toml")
+	}
+	assertContains(t, err.Error(), "No pyproject.toml found")
+}
+
+func TestUvLockOldImage(t *testing.T) {
+	_, configPath := writeUvLockWorkspace(t, workspaceOpts{})
+
+	cfg := mustValidate(t, map[string]any{
+		"python_version": "3.11",
+		"graphs":         map[string]any{"agent": "../../apps/agent/src/agent/graph.py:graph"},
+		"source":         map[string]any{"kind": "uv", "root": "../..", "package": "agent"},
+	})
+
+	_, _, err := ConfigToDocker(configPath, cfg, DockerOpts{
+		BaseImage: "langchain/langgraph-api:0.2.46",
+	})
+	if err == nil {
+		t.Fatal("expected error for old image without uv support")
+	}
+	assertContains(t, err.Error(), "requires a base image with uv support")
+}

libs/cli/internal/deploy/helpers.go

@@ -7,6 +7,7 @@ import (
 	"path/filepath"
 	"regexp"
 	"strings"
+	"time"
 )
 
 // APIKeyEnvNames lists the environment variable names checked (in order) when
@@ -251,6 +252,43 @@ func ResolvedReservedEnvVars() map[string]bool {
 	return result
 }
 
+// TerminalStatuses are deployment statuses that indicate completion.
+var TerminalStatuses = map[string]bool{
+	"DEPLOYED":      true,
+	"CREATE_FAILED": true,
+	"BUILD_FAILED":  true,
+	"DEPLOY_FAILED": true,
+	"SKIPPED":       true,
+}
+
+// PollDeploymentStatus polls a deployment until it reaches a terminal status or times out.
+func PollDeploymentStatus(client *HostBackendClient, deploymentID string, timeoutSeconds, pollIntervalSeconds int, onStatus func(string)) (string, error) {
+	deadline := time.Now().Add(time.Duration(timeoutSeconds) * time.Second)
+	interval := time.Duration(pollIntervalSeconds) * time.Second
+
+	for time.Now().Before(deadline) {
+		resp, err := client.ListRevisions(deploymentID, 1)
+		if err != nil {
+			return "", err
+		}
+		revisions, _ := resp["revisions"].([]any)
+		if len(revisions) == 0 {
+			time.Sleep(interval)
+			continue
+		}
+		rev, _ := revisions[0].(map[string]any)
+		status, _ := rev["status"].(string)
+		if onStatus != nil {
+			onStatus(status)
+		}
+		if TerminalStatuses[status] {
+			return status, nil
+		}
+		time.Sleep(interval)
+	}
+	return "", fmt.Errorf("deployment timed out after %d seconds", timeoutSeconds)
+}
+
 // SecretsFromEnv converts an env var map into a Secret slice, filtering out
 // reserved variable names and empty values.
 func SecretsFromEnv(envVars map[string]string) []Secret {

libs/cli/internal/deploy/helpers_test.go

@@ -0,0 +1,154 @@
+package deploy
+
+import (
+	"os"
+	"sort"
+	"testing"
+)
+
+func TestNormalizeImageName(t *testing.T) {
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"MyApp", "myapp"},
+		{"", "app"},
+		{"!!!", "app"},
+		{"my-app", "my-app"},
+		{"My Cool App", "my-cool-app"},
+		{"..leading-dots", "leading-dots"},
+		{"trailing-dots..", "trailing-dots"},
+		{"hello_world.v2", "hello_world.v2"},
+	}
+	for _, tc := range tests {
+		t.Run(tc.input, func(t *testing.T) {
+			got := NormalizeImageName(tc.input)
+			if got != tc.want {
+				t.Errorf("NormalizeImageName(%q) = %q, want %q", tc.input, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestNormalizeImageTag(t *testing.T) {
+	tests := []struct {
+		input   string
+		want    string
+		wantErr bool
+	}{
+		{"v1.2.3", "v1.2.3", false},
+		{"", "latest", false},
+		{"has space", "", true},
+		{"valid_tag-1.0", "valid_tag-1.0", false},
+		{"tag/slash", "", true},
+	}
+	for _, tc := range tests {
+		t.Run(tc.input, func(t *testing.T) {
+			got, err := NormalizeImageTag(tc.input)
+			if tc.wantErr {
+				if err == nil {
+					t.Errorf("NormalizeImageTag(%q) expected error, got nil", tc.input)
+				}
+				return
+			}
+			if err != nil {
+				t.Errorf("NormalizeImageTag(%q) unexpected error: %v", tc.input, err)
+				return
+			}
+			if got != tc.want {
+				t.Errorf("NormalizeImageTag(%q) = %q, want %q", tc.input, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestValidateDeploymentSelector(t *testing.T) {
+	tests := []struct {
+		name         string
+		deploymentID string
+		depName      string
+		wantErr      bool
+	}{
+		{"both empty", "", "", true},
+		{"id set", "abc-123", "", false},
+		{"name set", "", "my-deploy", false},
+		{"both set", "abc-123", "my-deploy", false},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			err := ValidateDeploymentSelector(tc.deploymentID, tc.depName)
+			if tc.wantErr && err == nil {
+				t.Error("expected error, got nil")
+			}
+			if !tc.wantErr && err != nil {
+				t.Errorf("unexpected error: %v", err)
+			}
+		})
+	}
+}
+
+func TestSecretsFromEnv(t *testing.T) {
+	envVars := map[string]string{
+		"MY_SECRET":         "value1",
+		"ANOTHER_SECRET":    "value2",
+		"LANGCHAIN_API_KEY": "should-be-filtered",
+		"POSTGRES_URI":      "should-be-filtered",
+		"EMPTY_VAR":         "",
+	}
+
+	secrets := SecretsFromEnv(envVars)
+
+	// Sort for deterministic comparison
+	sort.Slice(secrets, func(i, j int) bool {
+		return secrets[i].Name < secrets[j].Name
+	})
+
+	if len(secrets) != 2 {
+		t.Fatalf("expected 2 secrets, got %d: %+v", len(secrets), secrets)
+	}
+
+	if secrets[0].Name != "ANOTHER_SECRET" || secrets[0].Value != "value2" {
+		t.Errorf("unexpected secret[0]: %+v", secrets[0])
+	}
+	if secrets[1].Name != "MY_SECRET" || secrets[1].Value != "value1" {
+		t.Errorf("unexpected secret[1]: %+v", secrets[1])
+	}
+}
+
+func TestResolveAPIKey(t *testing.T) {
+	// Flag value takes precedence
+	got := ResolveAPIKey("flag-key", map[string]string{"LANGSMITH_API_KEY": "env-key"})
+	if got != "flag-key" {
+		t.Errorf("expected flag-key, got %q", got)
+	}
+
+	// envVars map is checked next
+	got = ResolveAPIKey("", map[string]string{"LANGSMITH_API_KEY": "env-key"})
+	if got != "env-key" {
+		t.Errorf("expected env-key, got %q", got)
+	}
+
+	// os.Getenv fallback
+	os.Setenv("LANGSMITH_API_KEY", "os-env-key")
+	defer os.Unsetenv("LANGSMITH_API_KEY")
+
+	got = ResolveAPIKey("", nil)
+	if got != "os-env-key" {
+		t.Errorf("expected os-env-key, got %q", got)
+	}
+
+	// Flag still takes precedence over os env
+	got = ResolveAPIKey("flag-value", nil)
+	if got != "flag-value" {
+		t.Errorf("expected flag-value, got %q", got)
+	}
+
+	// Empty everything returns empty
+	os.Unsetenv("LANGSMITH_API_KEY")
+	os.Unsetenv("LANGGRAPH_HOST_API_KEY")
+	os.Unsetenv("LANGCHAIN_API_KEY")
+	got = ResolveAPIKey("", nil)
+	if got != "" {
+		t.Errorf("expected empty string, got %q", got)
+	}
+}

libs/cli/internal/docker/docker.go

@@ -12,6 +12,8 @@ import (
 	"strconv"
 	"strings"
 	"time"
+
+	"github.com/langchain-ai/langgraph/libs/cli/internal/config"
 )
 
 // DefaultPostgresURI is the default connection string used when no custom
@@ -496,9 +498,21 @@ func BuildDockerImage(opts BuildImageOpts) error {
 		}
 	}
 
-	// Generate the Dockerfile. This is a placeholder that will call into
-	// the config package once ConfigToDocker is implemented.
-	dockerfile := generateDockerfileStub(opts)
+	// Generate the Dockerfile using the real config.ConfigToDocker.
+	dockerfile, additionalContexts, err := config.ConfigToDocker(opts.ConfigPath, opts.ConfigJSON, config.DockerOpts{
+		BaseImage:      opts.BaseImage,
+		APIVersion:     opts.APIVersion,
+		InstallCommand: opts.InstallCommand,
+		BuildCommand:   opts.BuildCommand,
+	})
+	if err != nil {
+		return fmt.Errorf("generating Dockerfile: %w", err)
+	}
+
+	// Add additional build contexts (for dependencies outside the main context).
+	for name, path := range additionalContexts {
+		args = append(args, "--build-context", fmt.Sprintf("%s=%s", name, path))
+	}
 
 	// Assemble the full command.
 	fullArgs := append(dockerCmd[1:], args...)
@@ -513,14 +527,3 @@ func BuildDockerImage(opts BuildImageOpts) error {
 
 	return cmd.Run()
 }
-
-// generateDockerfileStub is a placeholder that will be replaced by a call to
-// config.ConfigToDocker once that function is implemented in the config package.
-func generateDockerfileStub(opts BuildImageOpts) string {
-	// Placeholder: produce a minimal Dockerfile from the base image.
-	base := opts.BaseImage
-	if base == "" {
-		base = "langchain/langgraph-api"
-	}
-	return fmt.Sprintf("FROM %s\n", base)
-}

libs/cli/internal/root/root.go

@@ -8,6 +8,7 @@ import (
 	"path/filepath"
 	"strconv"
 	"strings"
+	"time"
 
 	"github.com/langchain-ai/langgraph/libs/cli/internal/config"
 	"github.com/langchain-ai/langgraph/libs/cli/internal/deploy"
@@ -596,8 +597,10 @@ Options:
 		EngineRuntimeMode: flags.engineRuntimeMode,
 	})
 
-	// Merge compose: infra + app overlay
-	fullCompose := infraYAML + composeSnippet
+	// Wrap the app config snippet into a valid compose overlay YAML.
+	// ConfigToCompose returns content indented at the service-property level
+	// (8 spaces), so we wrap it in the correct compose structure.
+	appOverlayYAML := "services:\n    langgraph-api:" + composeSnippet
 
 	// Pull
 	if flags.pull && flags.image == "" {
@@ -606,15 +609,25 @@ Options:
 		_ = lgexec.Run("docker", []string{"pull", tag}, lgexec.RunOpts{Verbose: flags.verbose})
 	}
 
-	// Write compose to temp file and run
-	tmpFile, err := os.CreateTemp("", "langgraph-compose-*.yml")
+	// Write infrastructure compose and app overlay to separate temp files.
+	// Docker compose handles merging when given multiple -f flags.
+	tmpInfra, err := os.CreateTemp("", "langgraph-infra-*.yml")
 	if err != nil {
 		errPrint(stderr, err.Error())
 		return 1
 	}
-	defer os.Remove(tmpFile.Name())
-	_, _ = tmpFile.WriteString(fullCompose)
-	tmpFile.Close()
+	defer os.Remove(tmpInfra.Name())
+	_, _ = tmpInfra.WriteString(infraYAML)
+	tmpInfra.Close()
+
+	tmpApp, err := os.CreateTemp("", "langgraph-app-*.yml")
+	if err != nil {
+		errPrint(stderr, err.Error())
+		return 1
+	}
+	defer os.Remove(tmpApp.Name())
+	_, _ = tmpApp.WriteString(appOverlayYAML)
+	tmpApp.Close()
 
 	composeCmd := "docker"
 	composeArgs := []string{"compose"}
@@ -623,7 +636,7 @@ Options:
 		composeArgs = nil
 	}
 
-	upArgs := append(composeArgs, "-f", tmpFile.Name(), "up")
+	upArgs := append(composeArgs, "-f", tmpInfra.Name(), "-f", tmpApp.Name(), "up")
 	if flags.wait {
 		upArgs = append(upArgs, "--wait")
 	} else {
@@ -926,7 +939,6 @@ Options:
 
 	_ = tag
 	_ = deploymentType
-	_ = noWait
 	_ = verbose
 	_ = remote
 	_ = name
@@ -1027,6 +1039,21 @@ Options:
 		return 1
 	}
 
+	if !noWait {
+		_, _ = fmt.Fprintln(stdout, "Waiting for deployment...")
+		finalStatus, pollErr := deploy.PollDeploymentStatus(client, depID, 300, 2, func(status string) {
+			_, _ = fmt.Fprintf(stdout, "  Status: %s\n", status)
+		})
+		if pollErr != nil {
+			errPrint(stderr, pollErr.Error())
+			return 1
+		}
+		if finalStatus != "DEPLOYED" {
+			errPrint(stderr, fmt.Sprintf("Deployment failed with status: %s", finalStatus))
+			return 1
+		}
+	}
+
 	_, _ = fmt.Fprintf(stdout, "%sDeployment updated successfully!%s\n", colorGreen, colorReset)
 	return 0
 }
@@ -1340,7 +1367,65 @@ Options:
 		payload["query"] = query
 	}
 
-	_ = follow // TODO: implement follow mode with polling
+	if follow {
+		payload["order"] = "asc"
+		seen := make(map[string]bool)
+		for {
+			var resp map[string]any
+			var err error
+			if logType == "build" {
+				if revisionID == "" {
+					revResp, rerr := client.ListRevisions(deploymentID, 1)
+					if rerr != nil {
+						errPrint(stderr, rerr.Error())
+						return 1
+					}
+					revisions, _ := revResp["revisions"].([]any)
+					if len(revisions) > 0 {
+						rev, _ := revisions[0].(map[string]any)
+						revisionID, _ = rev["id"].(string)
+					}
+				}
+				if revisionID == "" {
+					time.Sleep(2 * time.Second)
+					continue
+				}
+				resp, err = client.GetBuildLogs(deploymentID, revisionID, payload)
+			} else {
+				resp, err = client.GetDeployLogs(deploymentID, payload, revisionID)
+			}
+			if err != nil {
+				errPrint(stderr, err.Error())
+				return 1
+			}
+			logs, _ := resp["logs"].([]any)
+			for _, l := range logs {
+				entry, _ := l.(map[string]any)
+				id, _ := entry["id"].(string)
+				if id == "" {
+					// Fall back to timestamp+message as key
+					ts, _ := entry["timestamp"].(string)
+					msg, _ := entry["message"].(string)
+					id = ts + "|" + msg
+				}
+				if seen[id] {
+					continue
+				}
+				seen[id] = true
+				ts, _ := entry["timestamp"].(string)
+				lvl, _ := entry["level"].(string)
+				msg, _ := entry["message"].(string)
+				if ts != "" {
+					_, _ = fmt.Fprintf(stdout, "[%s] ", ts)
+				}
+				if lvl != "" {
+					_, _ = fmt.Fprintf(stdout, "[%s] ", lvl)
+				}
+				_, _ = fmt.Fprintln(stdout, msg)
+			}
+			time.Sleep(2 * time.Second)
+		}
+	}
 
 	var resp map[string]any
 	var err error

libs/cli/pyproject.toml

@@ -61,6 +61,9 @@ default-groups = ['dev']
 [tool.hatch.build.targets.wheel]
 include = ["langgraph_cli"]
 
+[tool.hatch.build.targets.wheel.hooks.custom]
+path = "hatch_build.py"
+
 [tool.pytest.ini_options]
 addopts = "--strict-markers --strict-config --durations=5 -vv"
 asyncio_mode = "auto"