multi-forge 0.2.0__py3-none-any.whl

forge/session/worktree/create.py

@@ -0,0 +1,332 @@
+"""Git worktree creation utilities.
+
+This module provides functions for creating git worktrees for session isolation.
+Each session can have its own worktree, enabling parallel work without conflicts.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..exceptions import (
+    BranchExistsError,
+    GitNotFoundError,
+    GitWorktreeError,
+    InvalidBranchNameError,
+    WorktreePathExistsError,
+)
+
+
+@dataclass
+class WorktreeResult:
+    """Result of worktree creation."""
+
+    worktree_path: str
+    branch: str
+    created_branch: bool  # True if a new branch was created
+
+
+def find_git_binary() -> str:
+    """Find git binary in PATH.
+
+    Returns:
+        Path to git binary.
+
+    Raises:
+        GitNotFoundError: If git is not found.
+    """
+    git_path = shutil.which("git")
+    if git_path is None:
+        raise GitNotFoundError()
+    return git_path
+
+
+def get_repo_root(cwd: Path | None = None) -> Path:
+    """Get the root of the git repository or worktree.
+
+    For worktrees, this returns the worktree root, not the main repository.
+    Use get_main_repo_root() if you need the main repository.
+
+    Args:
+        cwd: Starting directory (defaults to current).
+
+    Returns:
+        Path to repository/worktree root.
+
+    Raises:
+        GitWorktreeError: If not in a git repository.
+    """
+    git = find_git_binary()
+    start = cwd or Path.cwd()
+
+    result = subprocess.run(
+        [git, "rev-parse", "--show-toplevel"],
+        cwd=str(start),
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        raise GitWorktreeError("rev-parse", "not in a git repository", result.returncode)
+
+    return Path(result.stdout.strip())
+
+
+def get_main_repo_root(cwd: Path | None = None) -> Path:
+    """Get the root of the main git repository.
+
+    For worktrees, this returns the main repository root, not the worktree.
+    Uses git-common-dir to find the shared .git directory.
+
+    Args:
+        cwd: Starting directory (defaults to current).
+
+    Returns:
+        Path to main repository root.
+
+    Raises:
+        GitWorktreeError: If not in a git repository.
+    """
+    git = find_git_binary()
+    start = cwd or Path.cwd()
+
+    # Get the common git directory (shared by all worktrees)
+    result = subprocess.run(
+        [git, "rev-parse", "--path-format=absolute", "--git-common-dir"],
+        cwd=str(start),
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        raise GitWorktreeError("rev-parse", "not in a git repository", result.returncode)
+
+    common_dir = Path(result.stdout.strip())
+    if common_dir.name == ".git":
+        return common_dir.parent
+
+    # Handle edge case where common_dir might be .git/worktrees/name
+    while common_dir.name != ".git" and common_dir.parent != common_dir:
+        common_dir = common_dir.parent
+
+    if common_dir.name == ".git":
+        return common_dir.parent
+
+    return get_repo_root(cwd)
+
+
+def branch_exists(branch: str, cwd: Path | None = None) -> bool:
+    """Check if a git branch exists.
+
+    Uses refs/heads/ to specifically check for local branches,
+    avoiding false positives from tags or other refs.
+
+    Args:
+        branch: Branch name to check.
+        cwd: Working directory.
+
+    Returns:
+        True if branch exists as a local branch.
+    """
+    git = find_git_binary()
+
+    result = subprocess.run(
+        [git, "show-ref", "--verify", "--quiet", f"refs/heads/{branch}"],
+        cwd=str(cwd or Path.cwd()),
+        capture_output=True,
+        text=True,
+    )
+
+    return result.returncode == 0
+
+
+def get_worktree_for_branch(branch: str, cwd: Path | None = None) -> str | None:
+    """Find the worktree path that has a branch checked out.
+
+    Args:
+        branch: Branch name to look up.
+        cwd: Working directory.
+
+    Returns:
+        Worktree path if the branch is checked out, None otherwise.
+    """
+    git = find_git_binary()
+
+    result = subprocess.run(
+        [git, "worktree", "list", "--porcelain"],
+        cwd=str(cwd or Path.cwd()),
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        return None
+
+    # Porcelain format: blocks separated by blank lines, each has
+    # "worktree <path>" and "branch refs/heads/<name>"
+    current_path: str | None = None
+    for line in result.stdout.splitlines():
+        if line.startswith("worktree "):
+            current_path = line[len("worktree ") :]
+        elif line == f"branch refs/heads/{branch}":
+            return current_path
+
+    return None
+
+
+def validate_branch_name(branch: str) -> None:
+    """Validate a git branch name.
+
+    Uses git check-ref-format to validate the branch name.
+    This is called for explicit --branch values.
+
+    Args:
+        branch: Branch name to validate.
+
+    Raises:
+        InvalidBranchNameError: If branch name is invalid.
+    """
+    git = find_git_binary()
+
+    result = subprocess.run(
+        [git, "check-ref-format", "--branch", branch],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        reason = result.stderr.strip() if result.stderr else "invalid format"
+        raise InvalidBranchNameError(branch, reason)
+
+
+def sanitize_branch_name(session_name: str) -> str:
+    """Convert session name to valid git branch name.
+
+    Session names are already strict (lowercase alphanumeric + hyphens),
+    which are valid git branch names. This is mainly a pass-through.
+
+    Args:
+        session_name: The session name.
+
+    Returns:
+        Valid git branch name.
+    """
+    # Session names are validated as lowercase alphanumeric + hyphens
+    # which are valid git branch names - just pass through
+    return session_name
+
+
+def resolve_worktree_path(repo_root: Path, session_name: str) -> Path:
+    """Compute the worktree path for a session.
+
+    Worktree path: ../<project-name>-<session-name>
+    Places worktrees as siblings to the main repo.
+
+    Args:
+        repo_root: Path to the main repository.
+        session_name: The session name.
+
+    Returns:
+        Absolute path for the worktree.
+    """
+    project_name = repo_root.name
+    worktree_dir = f"{project_name}-{session_name}"
+    return (repo_root.parent / worktree_dir).resolve()
+
+
+def create_worktree(
+    session_name: str,
+    branch: str | None = None,
+    cwd: Path | None = None,
+    *,
+    force: bool = False,
+    replace_owned_stale_state: bool = False,
+) -> WorktreeResult:
+    """Create a git worktree for a session.
+
+    Args:
+        session_name: Session name (used for path and default branch).
+        branch: Override branch name (defaults to session_name).
+        cwd: Starting directory (defaults to current).
+        force: Replace conflicting branch/worktree state. Deletes a merged
+            branch and removes a clean registered worktree before recreating.
+            Hard constraints still apply: BranchInUseError (checked out
+            elsewhere), BranchNotMergedError (unmerged work), and non-worktree
+            paths (no .git file).
+        replace_owned_stale_state: Allow force recovery only when the caller
+            has already verified the target worktree/branch belong to the same
+            stale Forge session being replaced.
+
+    Returns:
+        WorktreeResult with path and branch info.
+
+    Raises:
+        GitNotFoundError: If git is not found.
+        GitWorktreeError: If worktree creation fails.
+        InvalidBranchNameError: If explicit branch name is invalid.
+        BranchExistsError: If branch already exists (or force with explicit --branch).
+        WorktreePathExistsError: If worktree path already exists (or not a git worktree).
+        BranchInUseError: If branch is checked out in another worktree (force only).
+        BranchNotMergedError: If branch has unmerged work (force only).
+    """
+    git = find_git_binary()
+    repo_root = get_repo_root(cwd)
+
+    if branch is not None:
+        validate_branch_name(branch)
+        target_branch = branch
+    else:
+        # Derive from session name (already valid)
+        target_branch = sanitize_branch_name(session_name)
+
+    worktree_path = resolve_worktree_path(repo_root, session_name)
+
+    # --force only replaces worktree state when the caller has proved the
+    # derived target belongs to the same stale Forge child being recovered.
+    # Worktree first (un-checks-out the branch), then branch.
+    if force and replace_owned_stale_state and worktree_path.exists():
+        git_file = worktree_path / ".git"
+        if not git_file.is_file():
+            # Not a registered git worktree — refuse to delete arbitrary dirs
+            raise WorktreePathExistsError(str(worktree_path))
+        from .cleanup import remove_worktree
+
+        main_root = get_main_repo_root(worktree_path)
+        remove_worktree(worktree_path, force=True, repo_root=main_root)
+        if worktree_path.exists():
+            raise WorktreePathExistsError(str(worktree_path))
+    elif worktree_path.exists():
+        raise WorktreePathExistsError(str(worktree_path))
+
+    if branch_exists(target_branch, repo_root):
+        if not force or not replace_owned_stale_state:
+            wt = get_worktree_for_branch(target_branch, repo_root)
+            raise BranchExistsError(target_branch, worktree=wt)
+        if branch is not None:
+            # Explicit --branch: refuse to destroy a user-chosen name
+            wt = get_worktree_for_branch(target_branch, repo_root)
+            raise BranchExistsError(target_branch, worktree=wt)
+        # --force with auto-derived branch: delete (respects git merge safety).
+        # BranchInUseError/BranchNotMergedError propagate as hard constraints.
+        from .cleanup import delete_branch as _delete_branch
+
+        _delete_branch(target_branch, cwd=repo_root, force=False)
+
+    result = subprocess.run(
+        [git, "worktree", "add", str(worktree_path), "-b", target_branch],
+        cwd=str(repo_root),
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        raise GitWorktreeError("add", result.stderr.strip(), result.returncode)
+
+    return WorktreeResult(
+        worktree_path=str(worktree_path),
+        branch=target_branch,
+        created_branch=True,
+    )

forge/sidecar/__init__.py

@@ -0,0 +1,29 @@
+"""Sidecar execution module for Multi-Forge.
+
+Bundles proxy + Claude Code in a Docker container with lifecycle coupling,
+port isolation, and version consistency. Not a security sandbox — Claude
+Code's native sandbox (Seatbelt/bubblewrap) handles that.
+"""
+
+from forge.sidecar.container import (
+    ContainerExistsError,
+    container_exists,
+    exec_in_container,
+    get_container_id,
+    parse_mounts,
+    run_sidecar_session,
+)
+from forge.sidecar.docker import is_container_running, is_docker_available
+from forge.sidecar.secrets import get_secrets_for_template
+
+__all__ = [
+    "ContainerExistsError",
+    "container_exists",
+    "exec_in_container",
+    "get_container_id",
+    "get_secrets_for_template",
+    "is_container_running",
+    "is_docker_available",
+    "parse_mounts",
+    "run_sidecar_session",
+]

forge/sidecar/container.py

@@ -0,0 +1,161 @@
+"""Container lifecycle management for sidecar Claude Code sessions.
+
+Bundles proxy + Claude Code in a Docker container. The key function
+`run_sidecar_session()` is the container equivalent of `invoke_claude()`
+— it runs interactively with inherited stdin/stdout/stderr.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from forge.sidecar.docker import _docker_name_filter
+
+
+class ContainerExistsError(RuntimeError):
+    """Raised when a container with the given name already exists."""
+
+    def __init__(self, container_name: str) -> None:
+        self.container_name = container_name
+        super().__init__(f"Container '{container_name}' already exists. " f"Remove with: docker rm -f {container_name}")
+
+
+def get_container_id(container_name: str) -> str | None:
+    """Get container ID by name (for running containers only)."""
+    result = subprocess.run(
+        ["docker", "ps", "-q", "-f", _docker_name_filter(container_name)],
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout.strip() or None
+
+
+def container_exists(container_name: str) -> bool:
+    """Check if a container exists by name (running OR stopped).
+
+    Uses `docker ps -a` to detect ALL containers, including stopped/exited ones.
+    """
+    result = subprocess.run(
+        ["docker", "ps", "-aq", "-f", _docker_name_filter(container_name)],
+        capture_output=True,
+        text=True,
+    )
+    return bool(result.stdout.strip())
+
+
+def run_sidecar_session(
+    *,
+    image: str,
+    template: str,
+    session_name: str,
+    project_dir: Path,
+    extra_mounts: list[tuple[str, str, str]] | None = None,
+    context_limit: int = 200000,
+    env_vars: dict[str, str] | None = None,
+    claude_args: list[str] | None = None,
+) -> int:
+    """Run Claude + proxy in a Docker container. Returns exit code.
+
+    Container lifecycle = Session lifecycle:
+    - Container starts when this function is called
+    - Container exits when Claude exits
+    - Container auto-cleaned via --rm flag
+    """
+    container_name = f"forge-{session_name}"
+
+    # Collision guard: detect both running AND stopped containers
+    if container_exists(container_name):
+        raise ContainerExistsError(container_name)
+
+    cmd = [
+        "docker",
+        "run",
+        "-it",
+        "--rm",
+        "--name",
+        container_name,
+        "-v",
+        f"{project_dir}:/workspace",
+        "-e",
+        f"FORGE_TEMPLATE={template}",
+        "-e",
+        f"CLAUDE_CODE_AUTO_COMPACT_WINDOW={context_limit}",
+        "-e",
+        f"FORGE_SESSION={session_name}",
+        "-e",
+        "FORGE_SIDECAR=1",
+        "-e",
+        "FORGE_LAUNCH_MODE=sidecar",
+        "-w",
+        "/workspace",
+    ]
+
+    if sys.platform == "linux":
+        uid, gid = os.getuid(), os.getgid()
+        cmd.extend(["--user", f"{uid}:{gid}"])
+
+    if extra_mounts:
+        for host_path, container_path, mode in extra_mounts:
+            cmd.extend(["-v", f"{host_path}:{container_path}:{mode}"])
+
+    # Write env vars to temp file instead of CLI args to avoid
+    # leaking secrets via `ps aux` (CR-022). Cleanup in finally.
+    env_file_path: str | None = None
+    try:
+        if env_vars:
+            fd, env_file_path = tempfile.mkstemp(prefix=".forge-env-", suffix=".env")
+            with os.fdopen(fd, "w") as f:
+                for k, v in env_vars.items():
+                    f.write(f"{k}={v}\n")
+            os.chmod(env_file_path, 0o600)
+            cmd.extend(["--env-file", env_file_path])
+
+        cmd.append(image)
+        if claude_args:
+            cmd.extend(claude_args)
+
+        result = subprocess.run(cmd)
+        return result.returncode
+    finally:
+        if env_file_path:
+            try:
+                os.unlink(env_file_path)
+            except OSError:
+                pass
+
+
+def exec_in_container(container_name: str, command: list[str]) -> int:
+    """Execute interactive command in running container."""
+    cmd = ["docker", "exec", "-it", container_name, *command]
+    result = subprocess.run(cmd)
+    return result.returncode
+
+
+def parse_mounts(mount_specs: tuple[str, ...]) -> list[tuple[str, str, str]]:
+    """Parse --mount flag specifications into (host, container, mode) tuples.
+
+    Format: "host_path:container_path[:ro|rw]"
+    Default mode is "rw" if not specified.
+    """
+    mounts = []
+    for spec in mount_specs:
+        parts = spec.split(":")
+
+        if len(parts) < 2:
+            raise ValueError(f"Invalid mount specification: {spec}. Expected 'host:container[:ro|rw]'")
+
+        host_path = parts[0]
+        container_path = parts[1]
+        mode = parts[2] if len(parts) > 2 else "rw"
+
+        if mode not in ("ro", "rw"):
+            raise ValueError(f"Invalid mount mode: {mode}. Must be 'ro' or 'rw'")
+
+        host_path = os.path.expanduser(host_path)
+        mounts.append((host_path, container_path, mode))
+
+    return mounts

forge/sidecar/docker.py

@@ -0,0 +1,86 @@
+"""Docker utility functions for sidecar execution.
+
+Low-level Docker operations used by the container lifecycle module.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+
+
+def _docker_name_filter(container_name: str) -> str:
+    """Build an exact-match docker ps name filter, escaping regex metacharacters."""
+    return f"name=^{re.escape(container_name)}$"
+
+
+def is_container_running(container_name: str) -> bool:
+    """Check if a Docker container is running by name.
+
+    Uses docker ps filtering with exact name match to avoid partial matches.
+
+    Args:
+        container_name: The container name to check.
+
+    Returns:
+        True if container exists and is running, False otherwise.
+    """
+    result = subprocess.run(
+        ["docker", "ps", "-q", "-f", _docker_name_filter(container_name)],
+        capture_output=True,
+        text=True,
+    )
+    return bool(result.stdout.strip())
+
+
+def is_docker_available() -> bool:
+    """Check if Docker is available and running.
+
+    Returns:
+        True if docker daemon is accessible, False otherwise.
+    """
+    try:
+        result = subprocess.run(
+            ["docker", "info"],
+            capture_output=True,
+            timeout=10,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return False
+
+
+def stop_container(container_name: str) -> bool:
+    """Stop a running container by name.
+
+    Args:
+        container_name: The container name to stop.
+
+    Returns:
+        True if container was stopped, False if container was not running.
+    """
+    result = subprocess.run(
+        ["docker", "stop", container_name],
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode == 0
+
+
+def remove_container(container_name: str, force: bool = False) -> bool:
+    """Remove a container by name.
+
+    Args:
+        container_name: The container name to remove.
+        force: If True, force remove even if running.
+
+    Returns:
+        True if container was removed, False otherwise.
+    """
+    cmd = ["docker", "rm"]
+    if force:
+        cmd.append("-f")
+    cmd.append(container_name)
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    return result.returncode == 0

forge/sidecar/secrets.py

@@ -0,0 +1,19 @@
+"""Secrets propagation for sidecar sessions.
+
+Forward required secrets (API keys, connection values) from the host
+environment into Docker containers. Secrets are template-dependent.
+
+Resolution order: environment variable -> credential file (~/.forge/credentials.yaml).
+
+Implementation lives in ``forge.core.auth.template_secrets``; this module
+re-exports the public API for backward compatibility.
+"""
+
+from __future__ import annotations
+
+from forge.core.auth.template_secrets import (
+    TEMPLATE_SECRETS,
+    get_secrets_for_template,
+)
+
+__all__ = ["TEMPLATE_SECRETS", "get_secrets_for_template"]