locki 0.0.1__tar.gz

locki-0.0.1/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.3
+Name: locki
+Version: 0.0.1
+Summary: Lock down agents in a VM, enabling mischief without consequences
+Requires-Dist: anyio>=4.12.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: rich>=14.3.3
+Requires-Dist: typer>=0.24.1
+Requires-Python: >=3.14, <3.15
+Description-Content-Type: text/markdown
+
+# locki

locki-0.0.1/README.md

@@ -0,0 +1 @@
+# locki

locki-0.0.1/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "locki"
+version = "0.0.1"
+description = "Lock down agents in a VM, enabling mischief without consequences"
+readme = "README.md"
+requires-python = ">=3.14,<3.15"
+dependencies = [
+    "anyio>=4.12.1",
+    "pydantic>=2.12.5",
+    "rich>=14.3.3",
+    "typer>=0.24.1",
+]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.15.7",
+    "wheel>=0.46.3",
+]
+
+[project.scripts]
+locki = "locki:app"
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 120
+target-version = "py314"
+lint.select = [
+    "E", "W", "F", "UP", "I", "B", "N", "C4", "Q", "SIM", "RUF", "TID", "ASYNC",
+]
+lint.ignore = ["E501"]
+force-exclude = true

locki-0.0.1/src/locki/__init__.py

@@ -0,0 +1,350 @@
+import functools
+import importlib.resources
+import os
+import pathlib
+import secrets
+import shlex
+import shutil
+import subprocess
+import sys
+import typing
+
+import typer
+
+from locki.async_typer import AsyncTyperWithAliases
+from locki.config import load_config
+from locki.console import console
+from locki.utils import run_command, verbosity
+
+app = AsyncTyperWithAliases(
+    name="locki",
+    help="Lima VM wrapper that protects worktrees by offering isolated execution environments.",
+    no_args_is_help=True,
+)
+
+LOCKI_HOME = pathlib.Path.home() / ".locki"
+LIMA_HOME = LOCKI_HOME / "lima"
+WORKTREES_HOME = LOCKI_HOME / "worktrees"
+
+
+@functools.cache
+def limactl() -> str:
+    bundled = importlib.resources.files("locki") / "data" / "bin" / "limactl"
+    if bundled.is_file():
+        return str(bundled)
+    system = shutil.which("limactl")
+    if system:
+        return system
+    console.error("limactl is not installed. Please install Lima or use a platform-specific locki wheel.")
+    sys.exit(1)
+
+
+async def run_in_vm(
+    command: list[str],
+    message: str,
+    env: dict[str, str] | None = None,
+    input: bytes | None = None,
+    check: bool = True,
+) -> subprocess.CompletedProcess[bytes]:
+    return await run_command(
+        [limactl(), "shell", "--start", "--preserve-env", "--tty=false", "locki", "--", "sudo", "-E", *command],
+        message,
+        env={"LIMA_HOME": str(LIMA_HOME)} | (env or {}),
+        cwd="/",
+        input=input,
+        check=check,
+    )
+
+
+async def ensure_vm() -> None:
+    LOCKI_HOME.mkdir(exist_ok=True)
+    LIMA_HOME.mkdir(exist_ok=True, parents=True)
+    WORKTREES_HOME.mkdir(parents=True, exist_ok=True)
+    await run_command(
+        [
+            limactl(),
+            "--tty=false",
+            "create",
+            str(importlib.resources.files("locki").joinpath("locki.yaml")),
+            "--mount-writable",
+            "--name=locki",
+        ],
+        "Preparing VM",
+        env={"LIMA_HOME": str(LIMA_HOME)},
+        cwd="/",
+        check=False,
+    )
+    await run_command(
+        [
+            limactl(),
+            "--tty=false",
+            "start",
+            "locki",
+        ],
+        "Starting VM",
+        env={"LIMA_HOME": str(LIMA_HOME)},
+        cwd="/",
+        check=False,
+    )
+
+
+@functools.cache
+def git_root() -> pathlib.Path:
+    current = pathlib.Path.cwd()
+    while True:
+        dot_git = current / ".git"
+        if dot_git.is_dir():
+            return current
+        if dot_git.is_file():
+            content = dot_git.read_text().strip()
+            if content.startswith("gitdir:"):
+                wt_gitdir = pathlib.Path(content.split(":", 1)[1].strip())
+                if not wt_gitdir.is_absolute():
+                    wt_gitdir = (current / wt_gitdir).resolve()
+                main_git_dir = (wt_gitdir / ".." / "..").resolve()
+                if main_git_dir.name == ".git":
+                    return main_git_dir.parent
+            return current
+        if current.parent == current:
+            console.error("Not inside a git repository.")
+            sys.exit(1)
+        current = current.parent
+
+
+async def find_worktree_for_branch(branch: str) -> pathlib.Path | None:
+    """Return the worktree path for a branch managed by locki, or None."""
+    result = await run_command(
+        ["git", "-C", str(git_root()), "worktree", "list", "--porcelain"],
+        "Listing worktrees",
+    )
+    current_path: pathlib.Path | None = None
+    for line in result.stdout.decode().splitlines():
+        if line.startswith("worktree "):
+            current_path = pathlib.Path(line.split(" ", 1)[1])
+        elif (
+            line.startswith("branch refs/heads/")
+            and line.split("/")[-1] == branch
+            and current_path
+            and current_path.is_relative_to(WORKTREES_HOME)
+        ):
+            return current_path
+    return None
+
+
+async def ensure_worktree(branch: str) -> pathlib.Path:
+    """Ensure a locki-managed worktree exists for the branch. Returns the worktree path."""
+    existing = await find_worktree_for_branch(branch)
+    if existing:
+        return existing
+
+    await run_command(
+        ["git", "-C", str(git_root()), "worktree", "prune"],
+        "Pruning stale git worktrees",
+    )
+
+    repo_name = git_root().name.replace("/", "-").replace(".", "-").lower()
+    safe_branch = branch.replace("/", "-").replace(".", "-").lower()
+    wt_id = f"{repo_name}--{safe_branch}--{secrets.token_hex(4)}"
+    wt_path = WORKTREES_HOME / wt_id
+    wt_path.mkdir(parents=True, exist_ok=True)
+
+    result = await run_command(
+        ["git", "-C", str(git_root()), "rev-parse", "--verify", f"refs/heads/{branch}"],
+        f"Checking if branch '{branch}' exists",
+        check=False,
+    )
+    if result.returncode != 0:
+        await run_command(
+            ["git", "-C", str(git_root()), "branch", branch],
+            f"Creating branch '{branch}'",
+        )
+
+    await run_command(
+        ["git", "-C", str(git_root()), "worktree", "add", str(wt_path), branch],
+        f"Creating worktree for '{branch}'",
+    )
+
+    return wt_path
+
+
+async def ensure_container(wt_id: str, wt_path: pathlib.Path, config) -> None:
+    """Ensure an Incus container exists for the given worktree (idempotent)."""
+    result = await run_in_vm(
+        ["incus", "list", "--format=csv", "--columns=n", wt_id],
+        "Checking container",
+        check=False,
+    )
+    if wt_id in result.stdout.decode():
+        await run_in_vm(
+            ["incus", "start", wt_id],
+            "Starting container",
+            check=False,
+        )
+        return
+
+    incus_image = config.get_incus_image()
+
+    local_path = git_root() / incus_image
+    if local_path.is_file():
+        local_file = local_path.resolve()
+        await run_command(
+            [limactl(), "copy", str(local_file), "locki:/tmp/image"],
+            "Copying image into VM",
+            env={"LIMA_HOME": str(LIMA_HOME)},
+            cwd="/",
+        )
+        await run_in_vm(
+            ["incus", "image", "import", "/tmp/image", f"--alias={wt_id}"],
+            "Importing container image",
+        )
+        await run_in_vm(["rm", "-f", "/tmp/image"], "Cleaning up image file", check=False)
+        image_ref = wt_id
+    else:
+        image_ref = incus_image
+
+    await run_in_vm(
+        ["incus", "init", image_ref, wt_id],
+        "Creating container",
+    )
+
+    if local_path.is_file():
+        await run_in_vm(
+            ["incus", "image", "delete", wt_id],
+            "Cleaning up imported image",
+            check=False,
+        )
+
+    await run_in_vm(
+        [
+            "incus",
+            "config",
+            "device",
+            "add",
+            wt_id,
+            "worktree",
+            "disk",
+            f"source={wt_path}",
+            f"path={wt_path}",
+        ],
+        "Mounting worktree into container",
+    )
+
+    await run_in_vm(
+        ["incus", "start", wt_id],
+        "Starting container",
+    )
+
+
+@app.command("shell", help="Open a shell in the per-branch container (creates branch/worktree/container if needed).")
+async def shell_cmd(
+    branch: typing.Annotated[str, typer.Argument(help="Branch name to work on")],
+    verbose: typing.Annotated[bool, typer.Option("-v", "--verbose", help="Show verbose output")] = False,
+):
+    with verbosity(verbose):
+        git_root()  # fail fast if not in a git repo
+
+        await ensure_vm()
+
+        wt_path = await ensure_worktree(branch)
+        wt_id = wt_path.relative_to(WORKTREES_HOME).parts[0]
+
+        config = load_config(git_root())
+        await ensure_container(wt_id, wt_path, config)
+
+    forwarded_env = {"TERM", "COLORTERM", "TERM_PROGRAM", "TERM_PROGRAM_VERSION", "LANG", "SSH_TTY"}
+
+    os.environ["LIMA_HOME"] = str(LIMA_HOME)
+    os.environ["LIMA_SHELLENV_ALLOW"] = ",".join(forwarded_env)
+
+    os.execvp(
+        limactl(),
+        [
+            limactl(),
+            "shell",
+            "--yes",
+            "--preserve-env",
+            "--start",
+            "locki",
+            "--",
+            "bash",
+            "-c",
+            " ".join(
+                [
+                    "sudo",
+                    "incus",
+                    "exec",
+                    shlex.quote(wt_id),
+                    "--cwd",
+                    shlex.quote(str(wt_path)),
+                    *(f"--env={env}=${env}" for env in forwarded_env),
+                    "--",
+                    "bash",
+                    "--login",
+                ]
+            ),
+        ],
+    )
+
+
+@app.command("remove", help="Remove a branch's worktree and container.")
+async def remove_cmd(
+    branch: typing.Annotated[str, typer.Argument(help="Branch name to remove")],
+    force: typing.Annotated[bool, typer.Option("--force", "-f", help="Skip safety checks")] = False,
+    verbose: typing.Annotated[bool, typer.Option("-v", "--verbose", help="Show verbose output")] = False,
+):
+    with verbosity(verbose):
+        wt_path = await find_worktree_for_branch(branch)
+
+        if wt_path is None:
+            console.info(f"No locki-managed worktree found for '{branch}', nothing to do.")
+            return
+
+        if not force and (await run_command(
+            ["git", "-C", str(wt_path), "status", "--porcelain"],
+            "Checking for uncommitted changes",
+            check=False,
+        )).stdout.strip():
+            console.error(f"Worktree for {branch} in {wt_path} has uncommitted changes. Commit or stash them, or use --force.")
+            sys.exit(1)
+
+        wt_id = wt_path.relative_to(WORKTREES_HOME).parts[0]
+
+        await run_in_vm(
+            ["incus", "delete", "--force", wt_id],
+            "Deleting container",
+            check=False,
+        )
+
+        await run_command(
+            ["git", "-C", str(git_root()), "worktree", "remove", "--force", str(wt_path)],
+            "Removing worktree",
+            check=False,
+        )
+
+
+@app.command("list", help="List branches with locki-managed worktrees.")
+async def list_cmd(
+    verbose: typing.Annotated[bool, typer.Option("-v", "--verbose", help="Show verbose output")] = False,
+):
+    with verbosity(verbose, show_success_status=False):
+        result = await run_command(
+            ["git", "-C", str(git_root()), "worktree", "list", "--porcelain"],
+            "Listing worktrees",
+        )
+
+    found = False
+    current_path: pathlib.Path | None = None
+    current_branch: str | None = None
+    for line in result.stdout.decode().splitlines():
+        if line.startswith("worktree "):
+            current_path = pathlib.Path(line.split(" ", 1)[1])
+            current_branch = None
+        elif line.startswith("branch refs/heads/"):
+            current_branch = line.removeprefix("branch refs/heads/")
+        elif line == "" and current_path and current_branch:
+            if current_path.is_relative_to(WORKTREES_HOME):
+                console.print(f"{current_branch}  [dim]{current_path}[/dim]")
+                found = True
+
+    if not found:
+        console.info("No locki-managed worktrees found.")

locki-0.0.1/src/locki/async_typer.py

@@ -0,0 +1,56 @@
+import asyncio
+import functools
+import inspect
+import sys
+
+import typer
+from typer.core import TyperGroup
+
+from locki.console import err_console
+
+
+class AsyncTyper(typer.Typer):
+    def command(self, *args, **kwargs):
+        parent_decorator = super().command(*args, **kwargs)
+
+        def decorator(f):
+            @functools.wraps(f)
+            def wrapped_f(*args, **kwargs):
+                if sys.stdout.isatty():
+                    sys.stdout.write("\x1b[>0u")
+                    sys.stdout.flush()
+                try:
+                    if inspect.iscoroutinefunction(f):
+                        return asyncio.run(f(*args, **kwargs))
+                    else:
+                        return f(*args, **kwargs)
+                except* Exception as eg:
+                    for exc in eg.exceptions:
+                        err_console.error(f"{type(exc).__name__}: {exc}")
+                    sys.exit(1)
+                finally:
+                    if sys.stdout.isatty():
+                        sys.stdout.write("\x1b[<u")
+                        sys.stdout.flush()
+
+            parent_decorator(wrapped_f)
+            return f
+
+        return decorator
+
+
+class AliasGroup(TyperGroup):
+    """Support comma/pipe-separated command name aliases, e.g. 'start|up'."""
+
+    def get_command(self, ctx, cmd_name):
+        for cmd in self.commands.values():
+            if cmd.name and cmd_name in cmd.name.replace(" ", "").split(","):
+                cmd_name = cmd.name
+                break
+        return super().get_command(ctx, cmd_name)
+
+
+class AsyncTyperWithAliases(AsyncTyper):
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault("cls", AliasGroup)
+        super().__init__(*args, **kwargs)

locki-0.0.1/src/locki/config.py

@@ -0,0 +1,38 @@
+import pathlib
+import platform
+import sys
+import tomllib
+
+import pydantic
+
+from locki.console import console
+
+DEFAULT_INCUS_IMAGES: dict[str, str] = {
+    "arm64": "locki-base",
+    "amd64": "locki-base",
+}
+
+
+class LockiConfig(pydantic.BaseModel):
+    incus_image: dict[str, str] = pydantic.Field(default_factory=lambda: dict(DEFAULT_INCUS_IMAGES))
+
+    def get_incus_image(self) -> str:
+        arch = platform.machine()
+        if arch not in self.incus_image:
+            console.error(
+                f"No incus_image configured for architecture '{arch}'. Available: {', '.join(self.incus_image)}"
+            )
+            sys.exit(1)
+        return self.incus_image[arch]
+
+
+def load_config(git_root: pathlib.Path) -> LockiConfig:
+    config_path = git_root / "locki.toml"
+    if not config_path.exists():
+        return LockiConfig()
+    try:
+        with open(config_path, "rb") as f:
+            return LockiConfig.model_validate(tomllib.load(f))
+    except (tomllib.TOMLDecodeError, pydantic.ValidationError) as e:
+        console.error(f"Invalid locki.toml: {e}")
+        sys.exit(1)

locki-0.0.1/src/locki/console.py

@@ -0,0 +1,22 @@
+from rich.console import Console
+
+
+class ExtendedConsole(Console):
+    def error(self, message: str):
+        self.print(f":boom: [bold red]ERROR[/bold red]: {message}")
+
+    def warning(self, message: str):
+        self.print(f":warning: [yellow]WARNING[/yellow]: {message}")
+
+    def hint(self, message: str):
+        self.print(f":bulb: [bright_cyan]HINT[/bright_cyan]: {message}")
+
+    def success(self, message: str):
+        self.print(f":white_check_mark: [green]SUCCESS[/green]: {message}")
+
+    def info(self, message: str):
+        self.print(f":memo: INFO: {message}")
+
+
+err_console = ExtendedConsole(stderr=True)
+console = ExtendedConsole()

locki-0.0.1/src/locki/locki.yaml

@@ -0,0 +1,115 @@
+minimumLimaVersion: "2.0.0"
+
+base:
+  - template:fedora
+
+containerd:
+  system: false
+  user: false
+
+mounts:
+  - location: "~/.locki/worktrees"
+    writable: true
+
+provision:
+  - mode: system
+    script: |
+      #!/bin/bash
+      set -euxo pipefail
+      if command -v incus; then exit 0; fi
+      echo "root:1000000:1000000000" >> /etc/subuid
+      echo "root:1000000:1000000000" >> /etc/subgid
+      dnf install -y --setopt install_weak_deps=False incus incus-client
+      systemctl enable --now incus
+      mkdir -p /var/cache/locki
+      incus admin init --preseed <<EOF
+      storage_pools:
+        - name: default
+          driver: dir
+      networks:
+        - name: incusbr0
+          type: bridge
+          config:
+            ipv4.address: 10.99.0.1/24
+            ipv4.nat: "true"
+            ipv6.address: none
+      profiles:
+        - name: default
+          config:
+            environment.PATH: /root/.local/bin:/opt/mise/shims:/var/cache/locki/pnpm:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+            environment.PNPM_HOME: /var/cache/locki/pnpm
+            environment.UV_CACHE_DIR: /var/cache/locki/uv
+            environment.COREPACK_ENABLE_DOWNLOAD_PROMPT: 0
+            environment.MISE_DATA_DIR: /opt/mise
+            environment.MISE_CONFIG_DIR: /opt/mise
+            environment.MISE_CACHE_DIR: /var/cache/locki/mise
+            environment.MISE_INSTALL_PATH: /usr/local/bin/mise
+            environment.MISE_TRUSTED_CONFIG_PATHS: /
+            environment.IS_SANDBOX: 1
+            security.nesting: "true"
+            security.privileged: "true"
+            raw.lxc: |
+              lxc.mount.auto = proc:rw sys:rw
+              lxc.cap.drop =
+          devices:
+            root:
+              path: /
+              pool: default
+              type: disk
+            eth0:
+              name: eth0
+              network: incusbr0
+              type: nic
+            kmsg:
+              path: /dev/kmsg
+              source: /dev/kmsg
+              type: unix-char
+            cache:
+              path: /var/cache/locki
+              source: /var/cache/locki
+              type: disk
+            claude-user:
+              path: /root/.claude
+              source: /root/.claude
+              type: disk
+            claude-managed:
+              path: /etc/claude-code
+              source: /etc/claude-code
+              type: disk
+      EOF
+  - mode: system
+    script: |
+      #!/bin/bash
+      set -euxo pipefail
+      if incus image list --format csv | grep -q locki-base; then exit 0; fi
+      mkdir -p /root/.claude
+      incus launch images:fedora/43 locki-base-builder
+      incus exec locki-base-builder -- bash <<'ENDBUILD'
+        set -euxo pipefail
+        curl --retry 10 --retry-all-errors https://mirrors.fedoraproject.org
+        dnf install -y \
+          https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \
+          https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
+        curl https://mise.run | sh
+        mise use -g claude@latest
+      ENDBUILD
+      incus stop locki-base-builder
+      incus publish locki-base-builder --alias locki-base
+      incus delete locki-base-builder
+  - mode: data
+    path: /etc/claude-code/managed-settings.json
+    content: |
+      {
+        "skipDangerousModePermissionPrompt": true,
+        "permissions": {
+          "defaultMode": "bypassPermissions"
+        }
+      }
+  - mode: data
+    path: /etc/claude-code/CLAUDE.md
+    content: |
+      You are running inside a VM, in a managed Incus container. This is an ephemeral environment designed to keep the main machine safe from malfunctioning agents. Before delving into your task, start by setting up the environment:
+
+      Container has Mise-en-place preinstalled. If there is `mise.toml` in the repo root, run `mise install` to install tools from it. Otherwise, check files like `.tool-versions`, `.nvmrc`, `pyproject.toml`, etc. or docs like `README.md`, `CONTRIBUTING.md` to determine needed tools and versions. Enable specific tool versions using e.g.: `mise use -g python@3.12.1`, `mise use -g node@22`, `mise use -g jq`. Container has Fedora 43 with RPM Fusion enabled -- install packages not available through Mise with `dnf install -y ...`.
+
+      `git` and `gh` are not configured inside the container. Do not attempt to use git or gh directly. When the user wants to commit, push, or open a PR, instruct them to `cd` in the worktree directory (matches on host and guest) and run the commands.

locki-0.0.1/src/locki/utils.py

@@ -0,0 +1,138 @@
+import contextlib
+import os
+import subprocess
+import sys
+import time
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+from io import BytesIO
+
+import anyio
+import anyio.abc
+from anyio import create_task_group
+from anyio.abc import ByteReceiveStream, TaskGroup
+from rich.console import Capture
+from rich.text import Text
+
+from locki.console import console, err_console
+
+
+async def _receive_stream(stream: ByteReceiveStream, buffer: BytesIO):
+    async for chunk in stream:
+        err_console.print(Text.from_ansi(chunk.decode(errors="replace")), style="dim")
+        buffer.write(chunk)
+
+
+@asynccontextmanager
+async def capture_output(
+    process: anyio.abc.Process,
+    stdout_buf: BytesIO,
+    stderr_buf: BytesIO,
+) -> AsyncIterator[TaskGroup]:
+    async with create_task_group() as tg:
+        if process.stdout:
+            tg.start_soon(_receive_stream, process.stdout, stdout_buf)
+        if process.stderr:
+            tg.start_soon(_receive_stream, process.stderr, stderr_buf)
+        yield tg
+
+
+async def run_command(
+    command: list[str],
+    message: str,
+    env: dict[str, str] | None = None,
+    cwd: str = ".",
+    check: bool = True,
+    input: bytes | None = None,
+) -> subprocess.CompletedProcess[bytes]:
+    env = env or {}
+    try:
+        with status(message):
+            err_console.print(f"Command: {command}", style="dim")
+            start_time = time.time()
+            async with await anyio.open_process(
+                command,
+                stdin=subprocess.PIPE if input else subprocess.DEVNULL,
+                env={**os.environ, **env},
+                cwd=cwd,
+            ) as process:
+                stdout_buf, stderr_buf = BytesIO(), BytesIO()
+                async with capture_output(process, stdout_buf, stderr_buf):
+                    if process.stdin and input:
+                        await process.stdin.send(input)
+                        await process.stdin.aclose()
+                    await process.wait()
+
+                if check and process.returncode != 0:
+                    raise subprocess.CalledProcessError(
+                        process.returncode or 0,
+                        command,
+                        stdout_buf.getvalue(),
+                        stderr_buf.getvalue(),
+                    )
+
+                elapsed = int(time.time() - start_time)
+                duration = (
+                    "" if elapsed < 5 else f"({elapsed}s)" if elapsed < 60 else f"({elapsed // 60}m{elapsed % 60}s)"
+                )
+
+                if SHOW_SUCCESS_STATUS.get():
+                    console.print(f"{message} [[green]DONE[/green]] [dim]{duration}[/dim]")
+                return subprocess.CompletedProcess(
+                    command, process.returncode or 0, stdout_buf.getvalue(), stderr_buf.getvalue()
+                )
+    except FileNotFoundError:
+        console.print(f"{message} [[red]ERROR[/red]]")
+        console.error(f"{command[0]} is not installed. Please install it first.")
+        sys.exit(1)
+    except subprocess.CalledProcessError as e:
+        console.print(f"{message} [[red]ERROR[/red]]")
+        err_console.print(f"[red]Exit code: {e.returncode}[/red]")
+        if e.stderr:
+            err_console.print(f"[red]Stderr: {e.stderr.decode(errors='replace').strip()}[/red]")
+        raise
+
+
+IN_VERBOSITY_CONTEXT: ContextVar[bool] = ContextVar("in_verbosity_context", default=False)
+VERBOSE: ContextVar[bool] = ContextVar("verbose", default=False)
+SHOW_SUCCESS_STATUS: ContextVar[bool] = ContextVar("show_success_status", default=True)
+
+
+@contextlib.contextmanager
+def status(message: str):
+    if VERBOSE.get():
+        console.print(f"{message}...")
+        yield
+    elif SHOW_SUCCESS_STATUS.get():
+        err_console.print(f"\n[bold]{message}[/bold]")
+        with console.status(f"{message}...", spinner="dots"):
+            yield
+    else:
+        err_console.print(f"\n[bold]{message}[/bold]")
+        yield
+
+
+@contextlib.contextmanager
+def verbosity(verbose: bool, show_success_status: bool = True):
+    if IN_VERBOSITY_CONTEXT.get():
+        yield
+        return
+
+    IN_VERBOSITY_CONTEXT.set(True)
+    token_verbose = VERBOSE.set(verbose)
+    token_status = SHOW_SUCCESS_STATUS.set(show_success_status)
+    capture: Capture | None = None
+    try:
+        with err_console.capture() if not verbose else contextlib.nullcontext() as capture:
+            yield
+    except Exception:
+        if not verbose and capture and (logs := capture.get().strip()):
+            err_console.print("\n[yellow]--- Captured logs ---[/yellow]\n")
+            err_console.print(Text.from_ansi(logs, style="dim"))
+            err_console.print("\n[red]------- Error -------[/red]\n")
+        raise
+    finally:
+        VERBOSE.reset(token_verbose)
+        IN_VERBOSITY_CONTEXT.set(False)
+        SHOW_SUCCESS_STATUS.reset(token_status)