import json
import shlex
from typing import Dict, List, Optional, Union, Literal
from pathlib import Path


from e2b.exceptions import BuildException, InvalidArgumentException
from e2b.template.consts import STACK_TRACE_DEPTH, RESOLVE_SYMLINKS
from e2b.template.dockerfile_parser import parse_dockerfile
from e2b.template.readycmd import ReadyCmd, wait_for_file
from e2b.template.types import (
    CopyItem,
    Instruction,
    TemplateType,
    RegistryConfig,
    InstructionType,
)
from e2b.template.utils import (
    calculate_files_hash,
    get_caller_directory,
    make_traceback,
    pad_octal,
    read_dockerignore,
    read_gcp_service_account_json,
    get_caller_frame,
    validate_relative_path,
)
from types import TracebackType


class TemplateBuilder:
    """
    Builder class for adding instructions to an E2B template.

    All methods return self to allow method chaining.
    """

    def __init__(self, template: "TemplateBase"):
        self._template = template

    def copy(
        self,
        src: Union[Union[str, Path], List[Union[str, Path]]],
        dest: Union[str, Path],
        force_upload: Optional[Literal[True]] = None,
        user: Optional[str] = None,
        mode: Optional[int] = None,
        resolve_symlinks: Optional[bool] = None,
        gzip: Optional[bool] = None,
    ) -> "TemplateBuilder":
        """
        Copy files or directories from the local filesystem into the template.

        :param src: Source file(s) or directory path(s) to copy
        :param dest: Destination path in the template
        :param force_upload: Force upload even if files are cached
        :param user: User and optionally group (user:group) to own the files
        :param mode: File permissions in octal format (e.g., 0o755)
        :param resolve_symlinks: Whether to resolve symlinks
        :param gzip: Whether to gzip the files before upload (default: True)

        :return: `TemplateBuilder` class

        Example
        ```python
        template.copy('requirements.txt', '/home/user/')
        template.copy(['app.py', 'config.py'], '/app/', mode=0o755)
        ```
        """
        srcs = [src] if isinstance(src, (str, Path)) else src

        # Get the caller frame for stack trace in validation errors
        caller_frame = get_caller_frame(STACK_TRACE_DEPTH - 1)
        stack_trace = make_traceback(caller_frame)

        for src_item in srcs:
            src_string = str(src_item)

            # Validate that the source path is a relative path within the context directory
            validate_relative_path(src_string, stack_trace)

            args = [
                src_string,
                str(dest),
                user or "",
                pad_octal(mode) if mode else "",
            ]

            instruction: Instruction = {
                "type": InstructionType.COPY,
                "args": args,
                "force": force_upload or self._template._force_next_layer,
                "forceUpload": force_upload,
                "resolveSymlinks": resolve_symlinks,
                "gzip": gzip,
            }

            self._template._instructions.append(instruction)

            # Collect one stack trace per pushed instruction so build steps
            # stay aligned with their stack traces when copying multiple
            # sources
            self._template._collect_stack_trace()

        return self

    def copy_items(self, items: List[CopyItem]) -> "TemplateBuilder":
        """
        Copy multiple files or directories using a list of copy items.

        :param items: List of CopyItem dictionaries with src, dest, and optional parameters

        :return: `TemplateBuilder` class

        Example
        ```python
        template.copy_items([
            {'src': 'app.py', 'dest': '/app/'},
            {'src': 'config.py', 'dest': '/app/', 'mode': 0o644}
        ])
        ```
        """
        # Get the stack trace at the copy_items call site
        caller_frame = get_caller_frame(STACK_TRACE_DEPTH - 1)
        stack_trace = make_traceback(caller_frame)

        def _copy_items():
            for item in items:
                try:
                    self.copy(
                        item["src"],
                        item["dest"],
                        item.get("forceUpload"),
                        item.get("user"),
                        item.get("mode"),
                        item.get("resolveSymlinks"),
                        item.get("gzip"),
                    )
                except Exception as error:
                    # Re-raise the error with the captured stack trace
                    if stack_trace is not None:
                        raise error.with_traceback(stack_trace)
                    raise

        # Use the override so each copied item collects this stack trace,
        # keeping build steps aligned with their stack traces
        self._template._run_in_stack_trace_override_context(_copy_items, stack_trace)
        return self

    def remove(
        self,
        path: Union[Union[str, Path], List[Union[str, Path]]],
        force: bool = False,
        recursive: bool = False,
        user: Optional[str] = None,
    ) -> "TemplateBuilder":
        """
        Remove files or directories in the template.

        :param path: File(s) or directory path(s) to remove
        :param force: Force removal without prompting
        :param recursive: Remove directories recursively
        :param user: User to run the command as

        :return: `TemplateBuilder` class

        Example
        ```python
        template.remove('/tmp/cache', recursive=True, force=True)
        template.remove('/tmp/cache', recursive=True, force=True, user='root')
        ```
        """
        paths = [path] if isinstance(path, (str, Path)) else path
        args = ["rm"]
        if recursive:
            args.append("-r")
        if force:
            args.append("-f")
        args.extend([shlex.quote(str(p)) for p in paths])

        return self._template._run_in_new_stack_trace_context(
            lambda: self.run_cmd(" ".join(args), user=user)
        )

    def rename(
        self,
        src: Union[str, Path],
        dest: Union[str, Path],
        force: bool = False,
        user: Optional[str] = None,
    ) -> "TemplateBuilder":
        """
        Rename or move a file or directory in the template.

        :param src: Source path
        :param dest: Destination path
        :param force: Force rename without prompting
        :param user: User to run the command as

        :return: `TemplateBuilder` class

        Example
        ```python
        template.rename('/tmp/old.txt', '/tmp/new.txt')
        template.rename('/tmp/old.txt', '/tmp/new.txt', user='root')
        ```
        """
        args = ["mv", shlex.quote(str(src)), shlex.quote(str(dest))]
        if force:
            args.append("-f")

        return self._template._run_in_new_stack_trace_context(
            lambda: self.run_cmd(" ".join(args), user=user)
        )

    def make_dir(
        self,
        path: Union[Union[str, Path], List[Union[str, Path]]],
        mode: Optional[int] = None,
        user: Optional[str] = None,
    ) -> "TemplateBuilder":
        """
        Create directory(ies) in the template.

        :param path: Directory path(s) to create
        :param mode: Directory permissions in octal format (e.g., 0o755)
        :param user: User to run the command as

        :return: `TemplateBuilder` class

        Example
        ```python
        template.make_dir('/app/data', mode=0o755)
        template.make_dir(['/app/logs', '/app/cache'])
        template.make_dir('/app/data', mode=0o755, user='root')
        ```
        """
        path_list = [path] if isinstance(path, (str, Path)) else path
        args = ["mkdir", "-p"]
        if mode:
            args.append(f"-m {pad_octal(mode)}")
        args.extend([shlex.quote(str(p)) for p in path_list])

        return self._template._run_in_new_stack_trace_context(
            lambda: self.run_cmd(" ".join(args), user=user)
        )

    def make_symlink(
        self,
        src: Union[str, Path],
        dest: Union[str, Path],
        user: Optional[str] = None,
        force: bool = False,
    ) -> "TemplateBuilder":
        """
        Create a symbolic link in the template.

        :param src: Source path (target of the symlink)
        :param dest: Destination path (location of the symlink)
        :param user: User to run the command as
        :param force: Force symlink without prompting

        :return: `TemplateBuilder` class

        Example
        ```python
        template.make_symlink('/usr/bin/python3', '/usr/bin/python')
        template.make_symlink('/usr/bin/python3', '/usr/bin/python', user='root')
        template.make_symlink('/usr/bin/python3', '/usr/bin/python', force=True)
        ```
        """
        args = ["ln", "-s"]
        if force:
            args.append("-f")
        args.extend([shlex.quote(str(src)), shlex.quote(str(dest))])
        return self._template._run_in_new_stack_trace_context(
            lambda: self.run_cmd(" ".join(args), user=user)
        )

    def run_cmd(
        self, command: Union[str, List[str]], user: Optional[str] = None
    ) -> "TemplateBuilder":
        """
        Run a shell command during template build.

        :param command: Command string or list of commands to run (joined with &&)
        :param user: User to run the command as

        :return: `TemplateBuilder` class

        Example
        ```python
        template.run_cmd('apt-get update')
        template.run_cmd(['pip install numpy', 'pip install pandas'])
        template.run_cmd('apt-get install vim', user='root')
        ```
        """
        commands = [command] if isinstance(command, str) else command
        args = [" && ".join(commands)]

        if user:
            args.append(user)

        instruction: Instruction = {
            "type": InstructionType.RUN,
            "args": args,
            "force": self._template._force_next_layer,
            "forceUpload": None,
        }
        self._template._instructions.append(instruction)
        self._template._collect_stack_trace()
        return self

    def set_workdir(self, workdir: Union[str, Path]) -> "TemplateBuilder":
        """
        Set the working directory for subsequent commands in the template.

        :param workdir: Path to set as the working directory

        :return: `TemplateBuilder` class

        Example
        ```python
        template.set_workdir('/app')
        ```
        """
        instruction: Instruction = {
            "type": InstructionType.WORKDIR,
            "args": [str(workdir)],
            "force": self._template._force_next_layer,
            "forceUpload": None,
        }
        self._template._instructions.append(instruction)
        self._template._collect_stack_trace()
        return self

    def set_user(self, user: str) -> "TemplateBuilder":
        """
        Set the user for subsequent commands in the template.

        :param user: Username to set

        :return: `TemplateBuilder` class

        Example
        ```python
        template.set_user('root')
        ```
        """
        instruction: Instruction = {
            "type": InstructionType.USER,
            "args": [user],
            "force": self._template._force_next_layer,
            "forceUpload": None,
        }
        self._template._instructions.append(instruction)
        self._template._collect_stack_trace()
        return self

    def pip_install(
        self, packages: Optional[Union[str, List[str]]] = None, g: bool = True
    ) -> "TemplateBuilder":
        """
        Install Python packages using pip.

        :param packages: Package name(s) to install. If None, runs 'pip install .' in the current directory
        :param g: Install packages globally (default: True). If False, installs for user only

        :return: `TemplateBuilder` class

        Example
        ```python
        template.pip_install('numpy')
        template.pip_install(['pandas', 'scikit-learn'])
        template.pip_install('numpy', g=False)  # Install for user only
        template.pip_install()  # Installs from current directory
        ```
        """
        if isinstance(packages, str):
            packages = [packages]

        args = ["pip", "install"]
        if not g:
            args.append("--user")
        if packages:
            args.extend(packages)
        else:
            args.append(".")

        return self._template._run_in_new_stack_trace_context(
            lambda: self.run_cmd(" ".join(args), user="root" if g else None)
        )

    def npm_install(
        self,
        packages: Optional[Union[str, List[str]]] = None,
        g: Optional[bool] = False,
        dev: Optional[bool] = False,
    ) -> "TemplateBuilder":
        """
        Install Node.js packages using npm.

        :param packages: Package name(s) to install. If None, installs from package.json
        :param g: Install packages globally
        :param dev: Install packages as dev dependencies

        :return: `TemplateBuilder` class

        Example
        ```python
        template.npm_install('express')
        template.npm_install(['lodash', 'axios'])
        template.npm_install('typescript', g=True)
        template.npm_install()  # Installs from package.json
        ```
        """
        if isinstance(packages, str):
            packages = [packages]

        args = ["npm", "install"]
        if g:
            args.append("-g")
        if dev:
            args.append("--save-dev")
        if packages:
            args.extend(packages)

        return self._template._run_in_new_stack_trace_context(
            lambda: self.run_cmd(" ".join(args), user="root" if g else None)
        )

    def bun_install(
        self,
        packages: Optional[Union[str, List[str]]] = None,
        g: Optional[bool] = False,
        dev: Optional[bool] = False,
    ) -> "TemplateBuilder":
        """
        Install Bun packages using bun.

        :param packages: Package name(s) to install. If None, installs from package.json
        :param g: Install packages globally
        :param dev: Install packages as dev dependencies

        :return: `TemplateBuilder` class

        Example
        ```python
        template.bun_install('express')
        template.bun_install(['lodash', 'axios'])
        template.bun_install('tsx', g=True)
        template.bun_install('typescript', dev=True)
        template.bun_install()  // Installs from package.json
        ```
        """
        if isinstance(packages, str):
            packages = [packages]

        args = ["bun", "install"]
        if g:
            args.append("-g")
        if dev:
            args.append("--dev")
        if packages:
            args.extend(packages)

        return self._template._run_in_new_stack_trace_context(
            lambda: self.run_cmd(" ".join(args), user="root" if g else None)
        )

    def apt_install(
        self,
        packages: Union[str, List[str]],
        no_install_recommends: bool = False,
        fix_missing: bool = False,
    ) -> "TemplateBuilder":
        """
        Install system packages using apt-get.

        :param packages: Package name(s) to install
        :param no_install_recommends: Whether to install recommended packages
        :param fix_missing: Whether to fix missing packages

        :return: `TemplateBuilder` class

        Example
        ```python
        template.apt_install('vim')
        template.apt_install(['git', 'curl', 'wget'])
        template.apt_install('vim', fix_missing=True)
        ```
        """
        if isinstance(packages, str):
            packages = [packages]

        return self._template._run_in_new_stack_trace_context(
            lambda: self.run_cmd(
                [
                    "apt-get update",
                    f"DEBIAN_FRONTEND=noninteractive DEBCONF_NOWARNINGS=yes apt-get install -y {'--no-install-recommends ' if no_install_recommends else ''}{'--fix-missing ' if fix_missing else ''}{' '.join(packages)}",
                ],
                user="root",
            )
        )

    def add_mcp_server(self, servers: Union[str, List[str]]) -> "TemplateBuilder":
        """
        Install MCP servers using mcp-gateway.

        Note: Requires a base image with mcp-gateway pre-installed (e.g., mcp-gateway).

        :param servers: MCP server name(s)

        :return: `TemplateBuilder` class

        Example
        ```python
        template.add_mcp_server('exa')
        template.add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])
        ```
        """
        if self._template._base_template != "mcp-gateway":
            caller_frame = get_caller_frame(STACK_TRACE_DEPTH - 1)
            stack_trace = make_traceback(caller_frame)
            raise BuildException(
                "MCP servers can only be added to mcp-gateway template"
            ).with_traceback(stack_trace)

        if isinstance(servers, str):
            servers = [servers]

        return self._template._run_in_new_stack_trace_context(
            lambda: self.run_cmd(f"mcp-gateway pull {' '.join(servers)}", user="root")
        )

    def git_clone(
        self,
        url: str,
        path: Optional[Union[str, Path]] = None,
        branch: Optional[str] = None,
        depth: Optional[int] = None,
        user: Optional[str] = None,
    ) -> "TemplateBuilder":
        """
        Clone a git repository into the template.

        :param url: Git repository URL
        :param path: Destination path for the clone
        :param branch: Branch to clone
        :param depth: Clone depth for shallow clones
        :param user: User to run the command as

        :return: `TemplateBuilder` class

        Example
        ```python
        template.git_clone('https://github.com/user/repo.git', '/app/repo')
        template.git_clone('https://github.com/user/repo.git', branch='main', depth=1)
        template.git_clone('https://github.com/user/repo.git', '/app/repo', user='root')
        ```
        """
        args = ["git", "clone", shlex.quote(url)]
        if branch:
            args.append(f"--branch {shlex.quote(branch)}")
            args.append("--single-branch")
        if depth:
            args.append(f"--depth {depth}")
        if path:
            args.append(shlex.quote(str(path)))
        return self._template._run_in_new_stack_trace_context(
            lambda: self.run_cmd(" ".join(args), user=user)
        )

    def beta_dev_container_prebuild(
        self,
        devcontainer_directory: Union[str, Path],
    ) -> "TemplateBuilder":
        """
        Prebuild a devcontainer from the specified directory during the build process.

        :param devcontainer_directory: Path to the devcontainer directory

        :return: `TemplateBuilder` class

        Example
        ```python
        template.git_clone('https://myrepo.com/project.git', '/my-devcontainer')
        template.beta_dev_container_prebuild('/my-devcontainer')
        ```
        """
        if self._template._base_template != "devcontainer":
            caller_frame = get_caller_frame(STACK_TRACE_DEPTH - 1)
            stack_trace = make_traceback(caller_frame)
            raise BuildException(
                "Devcontainers can only used in the devcontainer template"
            ).with_traceback(stack_trace)

        return self._template._run_in_new_stack_trace_context(
            lambda: self.run_cmd(
                f"devcontainer build --workspace-folder {shlex.quote(str(devcontainer_directory))}",
                user="root",
            )
        )

    def beta_set_dev_container_start(
        self,
        devcontainer_directory: Union[str, Path],
    ) -> "TemplateFinal":
        """
        Start a devcontainer from the specified directory and set it as the start command.

        This method returns `TemplateFinal`, which means it must be the last method in the chain.

        :param devcontainer_directory: Path to the devcontainer directory

        :return: `TemplateFinal` class

        Example
        ```python
        # Simple start
        template.git_clone('https://myrepo.com/project.git', '/my-devcontainer')
        template.beta_set_devcontainer_start('/my-devcontainer')

        # With prebuild
        template.git_clone('https://myrepo.com/project.git', '/my-devcontainer')
        template.beta_dev_container_prebuild('/my-devcontainer')
        template.beta_set_dev_container_start('/my-devcontainer')
        ```
        """
        if self._template._base_template != "devcontainer":
            caller_frame = get_caller_frame(STACK_TRACE_DEPTH - 1)
            stack_trace = make_traceback(caller_frame)
            raise BuildException(
                "Devcontainers can only used in the devcontainer template"
            ).with_traceback(stack_trace)

        def _set_start():
            dir_ = shlex.quote(str(devcontainer_directory))
            return self.set_start_cmd(
                "sudo devcontainer up --workspace-folder "
                + dir_
                + " && sudo /prepare-exec.sh "
                + dir_
                + " | sudo tee /devcontainer.sh > /dev/null && sudo chmod +x /devcontainer.sh && sudo touch /devcontainer.up",
                wait_for_file("/devcontainer.up"),
            )

        return self._template._run_in_new_stack_trace_context(_set_start)

    def set_envs(self, envs: Dict[str, str]) -> "TemplateBuilder":
        """
        Set environment variables.
        Note: Environment variables defined here are available only during template build.

        :param envs: Dictionary of environment variable names and values

        :return: `TemplateBuilder` class

        Example
        ```python
        template.set_envs({'NODE_ENV': 'production', 'PORT': '8080'})
        ```
        """
        if len(envs) == 0:
            return self

        instruction: Instruction = {
            "type": InstructionType.ENV,
            "args": [item for key, value in envs.items() for item in [key, value]],
            "force": self._template._force_next_layer,
            "forceUpload": None,
        }
        self._template._instructions.append(instruction)
        self._template._collect_stack_trace()
        return self

    def skip_cache(self) -> "TemplateBuilder":
        """
        Skip cache for all subsequent build instructions from this point.

        Call this before any instruction to force it and all following layers
        to be rebuilt, ignoring any cached layers.

        :return: `TemplateBuilder` class

        Example
        ```python
        template.skip_cache().run_cmd('apt-get update')
        ```
        """
        self._template._force_next_layer = True
        return self

    def set_start_cmd(
        self, start_cmd: str, ready_cmd: Union[str, ReadyCmd]
    ) -> "TemplateFinal":
        """
        Set the command to start when the sandbox launches and the ready check command.

        :param start_cmd: Command to run when the sandbox starts
        :param ready_cmd: Command or ReadyCmd to check if the sandbox is ready

        :return: `TemplateFinal` class

        Example
        ```python
        # Using a string command
        template.set_start_cmd(
            'python app.py',
            'curl http://localhost:8000/health'
        )

        # Using ReadyCmd helpers
        from e2b import wait_for_port, wait_for_url

        template.set_start_cmd(
            'python -m http.server 8000',
            wait_for_port(8000)
        )

        template.set_start_cmd(
            'npm start',
            wait_for_url('http://localhost:3000/health', 200)
        )
        ```
        """
        self._template._start_cmd = start_cmd

        if isinstance(ready_cmd, ReadyCmd):
            ready_cmd = ready_cmd.get_cmd()

        self._template._ready_cmd = ready_cmd
        self._template._collect_stack_trace()
        return TemplateFinal(self._template)

    def set_ready_cmd(self, ready_cmd: Union[str, ReadyCmd]) -> "TemplateFinal":
        """
        Set the command to check if the sandbox is ready.

        :param ready_cmd: Command or ReadyCmd to check if the sandbox is ready

        :return: `TemplateFinal` class

        Example
        ```python
        # Using a string command
        template.set_ready_cmd('curl http://localhost:8000/health')

        # Using ReadyCmd helpers
        from e2b import wait_for_port, wait_for_file, wait_for_process

        template.set_ready_cmd(wait_for_port(3000))

        template.set_ready_cmd(wait_for_file('/tmp/ready'))

        template.set_ready_cmd(wait_for_process('nginx'))
        ```
        """
        if isinstance(ready_cmd, ReadyCmd):
            ready_cmd = ready_cmd.get_cmd()

        self._template._ready_cmd = ready_cmd
        self._template._collect_stack_trace()
        return TemplateFinal(self._template)


class TemplateFinal:
    """
    Final template state after start/ready commands are set.
    """

    def __init__(self, template: "TemplateBase"):
        self._template = template


class TemplateBase:
    """
    Base class for building E2B sandbox templates.
    """

    _logs_refresh_frequency = 0.2

    def __init__(
        self,
        file_context_path: Optional[Union[str, Path]] = None,
        file_ignore_patterns: Optional[List[str]] = None,
    ):
        """
        Create a new template builder instance.

        :param file_context_path: Base path for resolving relative file paths in copy operations
        :param file_ignore_patterns: List of glob patterns to ignore when copying files
        """
        self._default_base_image: str = "e2bdev/base"
        self._base_image: Optional[str] = self._default_base_image
        self._base_template: Optional[str] = None
        self._registry_config: Optional[RegistryConfig] = None
        self._start_cmd: Optional[str] = None
        self._ready_cmd: Optional[str] = None
        # Force the whole template to be rebuilt
        self._force: bool = False
        # Force the next layer to be rebuilt
        self._force_next_layer: bool = False
        self._instructions: List[Instruction] = []
        # If no file_context_path is provided, use the caller's directory
        self._file_context_path = (
            file_context_path.as_posix()
            if isinstance(file_context_path, Path)
            else (file_context_path or get_caller_directory(STACK_TRACE_DEPTH) or ".")
        )
        self._file_ignore_patterns: List[str] = file_ignore_patterns or []
        self._stack_traces: List[Union[TracebackType, None]] = []
        self._stack_traces_enabled: bool = True
        self._stack_traces_override: Optional[Union[TracebackType, None]] = None

    def skip_cache(self) -> "TemplateBase":
        """
        Skip cache for all subsequent build instructions from this point.

        :return: `TemplateBase` class

        Example
        ```python
        template.skip_cache().from_python_image('3.11')
        ```
        """
        self._force_next_layer = True
        return self

    def _collect_stack_trace(
        self, stack_traces_depth: int = STACK_TRACE_DEPTH
    ) -> "TemplateBase":
        """
        Collect the current stack trace for debugging purposes.

        :param stack_traces_depth: Depth to traverse in the call stack

        :return: `TemplateBase` class
        """
        if not self._stack_traces_enabled:
            return self

        # Use the override if set, otherwise get the caller frame
        if self._stack_traces_override is not None:
            self._stack_traces.append(self._stack_traces_override)
            return self

        stack = get_caller_frame(stack_traces_depth)
        self._stack_traces.append(make_traceback(stack))
        return self

    def _disable_stack_trace(self) -> "TemplateBase":
        """
        Temporarily disable stack trace collection.

        :return: `TemplateBase` class
        """
        self._stack_traces_enabled = False
        return self

    def _enable_stack_trace(self) -> "TemplateBase":
        """
        Re-enable stack trace collection.

        :return: `TemplateBase` class
        """
        self._stack_traces_enabled = True
        return self

    def _run_in_new_stack_trace_context(self, fn):
        """
        Execute a function in a clean stack trace context.

        :param fn: Function to execute

        :return: The result of the function
        """
        self._disable_stack_trace()
        try:
            result = fn()
        finally:
            self._enable_stack_trace()
        self._collect_stack_trace(STACK_TRACE_DEPTH + 1)
        return result

    def _run_in_stack_trace_override_context(
        self, fn, stack_trace_override: Optional[Union[TracebackType, None]]
    ):
        """
        Execute a function with a manual stack trace override.

        :param fn: Function to execute
        :param stack_trace_override: Stack trace to use instead of auto-collecting

        :return: The result of the function
        """
        self._stack_traces_override = stack_trace_override
        try:
            return fn()
        finally:
            self._stack_traces_override = None

    # Built-in image mixins
    def from_debian_image(self, variant: str = "stable") -> TemplateBuilder:
        """
        Start template from a Debian base image.

        :param variant: Debian image variant

        :return: `TemplateBuilder` class

        Example
        ```python
        Template().from_debian_image('bookworm')
        ```
        """
        return self._run_in_new_stack_trace_context(
            lambda: self.from_image(f"debian:{variant}")
        )

    def from_ubuntu_image(self, variant: str = "latest") -> TemplateBuilder:
        """
        Start template from an Ubuntu base image.

        :param variant: Ubuntu image variant (default: 'latest')

        :return: `TemplateBuilder` class

        Example
        ```python
        Template().from_ubuntu_image('24.04')
        ```
        """
        return self._run_in_new_stack_trace_context(
            lambda: self.from_image(f"ubuntu:{variant}")
        )

    def from_python_image(self, version: str = "3") -> TemplateBuilder:
        """
        Start template from a Python base image.

        :param version: Python version (default: '3')

        :return: `TemplateBuilder` class

        Example
        ```python
        Template().from_python_image('3')
        ```
        """
        return self._run_in_new_stack_trace_context(
            lambda: self.from_image(f"python:{version}")
        )

    def from_node_image(self, variant: str = "lts") -> TemplateBuilder:
        """
        Start template from a Node.js base image.

        :param variant: Node.js image variant (default: 'lts')

        :return: `TemplateBuilder` class

        Example
        ```python
        Template().from_node_image('24')
        ```
        """
        return self._run_in_new_stack_trace_context(
            lambda: self.from_image(f"node:{variant}")
        )

    def from_bun_image(self, variant: str = "latest") -> TemplateBuilder:
        """
        Start template from a Bun base image.

        :param variant: Bun image variant (default: 'latest')

        :return: `TemplateBuilder` class
        """
        return self._run_in_new_stack_trace_context(
            lambda: self.from_image(f"oven/bun:{variant}")
        )

    def from_base_image(self) -> TemplateBuilder:
        """
        Start template from the E2B base image (e2bdev/base:latest).

        :return: `TemplateBuilder` class

        Example
        ```python
        Template().from_base_image()
        ```
        """
        return self._run_in_new_stack_trace_context(
            lambda: self.from_image(self._default_base_image)
        )

    def from_image(
        self,
        image: str,
        username: Optional[str] = None,
        password: Optional[str] = None,
    ) -> TemplateBuilder:
        """
        Start template from a Docker image.

        :param image: Docker image name (e.g., 'ubuntu:24.04')
        :param username: Username for private registry authentication
        :param password: Password for private registry authentication

        :return: `TemplateBuilder` class

        Example
        ```python
        Template().from_image('python:3')

        # With credentials (optional)
        Template().from_image('myregistry.com/myimage:latest', username='user', password='pass')
        ```
        """
        # Validate (and resolve the registry config) before mutating the builder.
        if username is not None or password is not None:
            if not username or not password:
                caller_frame = get_caller_frame(STACK_TRACE_DEPTH - 1)
                stack_trace = make_traceback(caller_frame)
                raise InvalidArgumentException(
                    "Both username and password are required when providing registry credentials"
                ).with_traceback(stack_trace)

            self._registry_config = {
                "type": "registry",
                "username": username,
                "password": password,
            }

        self._base_image = image
        self._base_template = None

        # If we should force the next layer and it's a FROM command, invalidate whole template
        if self._force_next_layer:
            self._force = True

        self._collect_stack_trace()
        return TemplateBuilder(self)

    def from_template(self, template: str) -> TemplateBuilder:
        """
        Start template from an existing E2B template.

        :param template: E2B template ID or alias

        :return: `TemplateBuilder` class

        Example
        ```python
        Template().from_template('my-base-template')
        ```
        """
        self._base_template = template
        self._base_image = None

        # If we should force the next layer and it's a FROM command, invalidate whole template
        if self._force_next_layer:
            self._force = True

        self._collect_stack_trace()
        return TemplateBuilder(self)

    def from_dockerfile(self, dockerfile_content_or_path: str) -> TemplateBuilder:
        """
        Parse a Dockerfile and convert it to Template SDK format.

        :param dockerfile_content_or_path: Either the Dockerfile content as a string, or a path to a Dockerfile file

        :return: `TemplateBuilder` class

        Example
        ```python
        Template().from_dockerfile('Dockerfile')
        Template().from_dockerfile('FROM python:3\\nRUN pip install numpy')
        ```
        """
        # Create a TemplateBuilder first to use its methods
        builder = TemplateBuilder(self)

        # Get the caller frame to use for stack trace override
        # -1 as we're going up the call stack from the parse_dockerfile function
        caller_frame = get_caller_frame(STACK_TRACE_DEPTH - 1)
        stack_trace_override = make_traceback(caller_frame)

        # Parse the dockerfile using the builder as the interface
        base_image = self._run_in_stack_trace_override_context(
            lambda: parse_dockerfile(dockerfile_content_or_path, builder),
            stack_trace_override,
        )
        self._base_image = base_image

        # If we should force the next layer and it's a FROM command, invalidate whole template
        if self._force_next_layer:
            self._force = True

        self._collect_stack_trace()
        return builder

    def from_aws_registry(
        self,
        image: str,
        access_key_id: str,
        secret_access_key: str,
        region: str,
    ) -> TemplateBuilder:
        """
        Start template from an AWS ECR registry image.

        :param image: Docker image name from AWS ECR
        :param access_key_id: AWS access key ID
        :param secret_access_key: AWS secret access key
        :param region: AWS region

        :return: `TemplateBuilder` class

        Example
        ```python
        Template().from_aws_registry(
            '123456789.dkr.ecr.us-west-2.amazonaws.com/myimage:latest',
            access_key_id='AKIA...',
            secret_access_key='...',
            region='us-west-2'
        )
        ```
        """
        self._base_image = image
        self._base_template = None

        # Set the registry config if provided
        self._registry_config = {
            "type": "aws",
            "awsAccessKeyId": access_key_id,
            "awsSecretAccessKey": secret_access_key,
            "awsRegion": region,
        }

        # If we should force the next layer and it's a FROM command, invalidate whole template
        if self._force_next_layer:
            self._force = True

        self._collect_stack_trace()
        return TemplateBuilder(self)

    def from_gcp_registry(
        self, image: str, service_account_json: Union[str, dict]
    ) -> TemplateBuilder:
        """
        Start template from a GCP Artifact Registry or Container Registry image.

        :param image: Docker image name from GCP registry
        :param service_account_json: Service account JSON string, dict, or path to JSON file

        :return: `TemplateBuilder` class

        Example
        ```python
        Template().from_gcp_registry(
            'gcr.io/myproject/myimage:latest',
            service_account_json='path/to/service-account.json'
        )
        ```
        """
        self._base_image = image
        self._base_template = None

        # Set the registry config if provided
        self._registry_config = {
            "type": "gcp",
            "serviceAccountJson": read_gcp_service_account_json(
                self._file_context_path, service_account_json
            ),
        }

        # If we should force the next layer and it's a FROM command, invalidate whole template
        if self._force_next_layer:
            self._force = True

        self._collect_stack_trace()
        return TemplateBuilder(self)

    @staticmethod
    def to_json(template: "TemplateClass") -> str:
        """
        Convert a template to JSON representation.

        :param template: The template to convert (TemplateBuilder or TemplateFinal instance)

        :return: JSON string representation of the template

        Example
        ```python
        template = Template().from_python_image('3').copy('app.py', '/app/')
        json_str = TemplateBase.to_json(template)
        ```
        """
        return json.dumps(
            template._template._serialize(
                template._template._instructions_with_hashes()
            ),
            indent=2,
        )

    @staticmethod
    def to_dockerfile(template: "TemplateClass") -> str:
        """
        Convert a template to Dockerfile format.

        Note: Templates based on other E2B templates cannot be converted to Dockerfile.

        :param template: The template to convert (TemplateBuilder or TemplateFinal instance)

        :return: Dockerfile string representation

        :raises ValueError: If the template is based on another E2B template or has no base image

        Example
        ```python
        template = Template().from_python_image('3').copy('app.py', '/app/')
        dockerfile = TemplateBase.to_dockerfile(template)
        ```
        """
        if template._template._base_template is not None:
            raise ValueError(
                "Cannot convert template built from another template to Dockerfile. "
                "Templates based on other templates can only be built using the E2B API."
            )

        if template._template._base_image is None:
            raise ValueError("No base image specified for template")

        dockerfile = f"FROM {template._template._base_image}\n"

        for instruction in template._template._instructions:
            if instruction["type"] == InstructionType.RUN:
                dockerfile += f"RUN {instruction['args'][0]}\n"
                continue

            if instruction["type"] == InstructionType.COPY:
                dockerfile += (
                    f"COPY {instruction['args'][0]} {instruction['args'][1]}\n"
                )
                continue

            if instruction["type"] == InstructionType.ENV:
                args = instruction["args"]
                values = []
                for i in range(0, len(args), 2):
                    values.append(f"{args[i]}={args[i + 1]}")
                dockerfile += f"ENV {' '.join(values)}\n"
                continue

            dockerfile += (
                f"{instruction['type'].value} {' '.join(instruction['args'])}\n"
            )

        if template._template._start_cmd:
            dockerfile += f"ENTRYPOINT {template._template._start_cmd}\n"

        return dockerfile

    def _instructions_with_hashes(
        self,
    ) -> List[Instruction]:
        """
        Add file hashes to COPY instructions for cache invalidation.

        :return: Copy of instructions list with filesHash added to COPY instructions
        """
        steps: List[Instruction] = []

        for index, instruction in enumerate(self._instructions):
            step: Instruction = {
                "type": instruction["type"],
                "args": instruction["args"],
                "force": instruction["force"],
                "forceUpload": instruction.get("forceUpload"),
                "resolveSymlinks": instruction.get("resolveSymlinks"),
                "gzip": instruction.get("gzip"),
            }

            if instruction["type"] == InstructionType.COPY:
                stack_trace = None
                if index + 1 < len(self._stack_traces):
                    stack_trace = self._stack_traces[index + 1]

                args = instruction.get("args", [])
                src = args[0] if len(args) > 0 else None
                dest = args[1] if len(args) > 1 else None
                if src is None or dest is None:
                    raise ValueError("Source path and destination path are required")

                resolve_symlinks = instruction.get("resolveSymlinks")
                step["filesHash"] = calculate_files_hash(
                    src,
                    dest,
                    self._file_context_path,
                    [
                        *self._file_ignore_patterns,
                        *read_dockerignore(self._file_context_path),
                    ],
                    resolve_symlinks
                    if resolve_symlinks is not None
                    else RESOLVE_SYMLINKS,
                    stack_trace,
                )

            steps.append(step)

        return steps

    def _serialize(self, steps: List[Instruction]) -> TemplateType:
        """
        Serialize the template to the API request format.

        :param steps: List of build instructions with file hashes

        :return: Template data formatted for the API
        """
        _steps: List[Instruction] = []

        for _, instruction in enumerate(steps):
            step: Instruction = {
                "type": instruction.get("type"),
                "args": instruction.get("args"),
                "force": instruction.get("force"),
            }

            files_hash = instruction.get("filesHash")
            if files_hash is not None:
                step["filesHash"] = files_hash

            force_upload = instruction.get("forceUpload")
            if force_upload is not None:
                step["forceUpload"] = force_upload

            _steps.append(step)

        template_data: TemplateType = {
            "steps": _steps,
            "force": self._force,
        }

        if self._base_image is not None:
            template_data["fromImage"] = self._base_image

        if self._base_template is not None:
            template_data["fromTemplate"] = self._base_template

        if self._registry_config is not None:
            template_data["fromImageRegistry"] = self._registry_config

        if self._start_cmd is not None:
            template_data["startCmd"] = self._start_cmd

        if self._ready_cmd is not None:
            template_data["readyCmd"] = self._ready_cmd

        return template_data


TemplateClass = Union[TemplateFinal, TemplateBuilder]