uvg 0.1.0__tar.gz

uvg-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.3
+Name: uvg
+Version: 0.1.0
+Summary: A global virtual environment manager built on top of uv
+Author: Noai-oss
+Author-email: Noai-oss <jiuwoxiao@outlook.com>
+Requires-Dist: typer>=0.24.1
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# uvg
+
+A global Python virtual environment manager built on `uv`. Environments default to `~/.uvg/venvs`.
+
+**`uv` for projects, `uvg` for environments.**
+
+Set `UVG_HOME` to move the uvg home directory.
+
+## Installation
+
+```bash
+uv tool install .
+# or
+uv tool install git+https://github.com/Noai-oss/uvg
+```
+
+## Quick Start
+
+```bash
+# Initialize shell integration (pick one)
+uvg init bash --profile ~/.bashrc
+uvg init zsh --profile ~/.zshrc
+uvg init pwsh --profile $PROFILE
+
+# Create and activate an environment
+uvg create myenv --python 3.12
+uvg activate myenv
+
+# Install packages
+uv pip install ruff black
+```
+
+## Commands
+
+| Command | Description | Example |
+| --- | --- | --- |
+| `uvg create <name>` | Create an environment | `uvg create data -p 3.11` |
+| `uvg activate <name>` | Activate an environment | `uvg activate data` |
+| `uvg remove <name>` | Remove an environment | `uvg remove data -y` |
+| `uvg init <shell>` | Initialize shell integration for `bash`, `zsh`, or `pwsh` | `uvg init zsh -p ~/.zshrc` |
+| `uvg env list` | List all environments | `uvg env list` |
+| `uvg env current` | Show current environment | `uvg env current` |
+| `uvg env dir` | Print the managed environments directory | `uvg env dir` |

uvg-0.1.0/README.md

@@ -0,0 +1,43 @@
+# uvg
+
+A global Python virtual environment manager built on `uv`. Environments default to `~/.uvg/venvs`.
+
+**`uv` for projects, `uvg` for environments.**
+
+Set `UVG_HOME` to move the uvg home directory.
+
+## Installation
+
+```bash
+uv tool install .
+# or
+uv tool install git+https://github.com/Noai-oss/uvg
+```
+
+## Quick Start
+
+```bash
+# Initialize shell integration (pick one)
+uvg init bash --profile ~/.bashrc
+uvg init zsh --profile ~/.zshrc
+uvg init pwsh --profile $PROFILE
+
+# Create and activate an environment
+uvg create myenv --python 3.12
+uvg activate myenv
+
+# Install packages
+uv pip install ruff black
+```
+
+## Commands
+
+| Command | Description | Example |
+| --- | --- | --- |
+| `uvg create <name>` | Create an environment | `uvg create data -p 3.11` |
+| `uvg activate <name>` | Activate an environment | `uvg activate data` |
+| `uvg remove <name>` | Remove an environment | `uvg remove data -y` |
+| `uvg init <shell>` | Initialize shell integration for `bash`, `zsh`, or `pwsh` | `uvg init zsh -p ~/.zshrc` |
+| `uvg env list` | List all environments | `uvg env list` |
+| `uvg env current` | Show current environment | `uvg env current` |
+| `uvg env dir` | Print the managed environments directory | `uvg env dir` |

uvg-0.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+[project]
+name = "uvg"
+version = "0.1.0"
+description = "A global virtual environment manager built on top of uv"
+readme = "README.md"
+authors = [
+    { name = "Noai-oss", email = "jiuwoxiao@outlook.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "typer>=0.24.1",
+]
+
+[project.scripts]
+uvg = "uvg.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "ruff>=0.15.11",
+    "ty>=0.0.31",
+    "typos>=1.45.1",
+]
+
+[tool.git-cliff.changelog]
+header = """
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+"""
+body = """
+{% if version %}\
+    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}\
+    ## [Unreleased]
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | striptags | trim | upper_first }}
+    {% for commit in commits %}
+        - {% if commit.scope %}*({{ commit.scope }})* {% endif %}{% if commit.breaking %}[BREAKING] {% endif %}{{ commit.message | upper_first }}\
+    {% endfor %}
+{% endfor %}
+"""
+footer = """
+
+<!-- generated by git-cliff -->
+"""
+trim = true
+postprocessors = [
+    { pattern = "<REPO>", replace = "https://github.com/Noai-oss/uvg" },
+]
+
+[tool.git-cliff.git]
+conventional_commits = true
+filter_unconventional = true
+require_conventional = false
+split_commits = false
+commit_preprocessors = [
+    { pattern = "^(\\w+(?:\\([^)]*\\))?!?:)\\s*[^\\x00-\\x7F]+\\s*", replace = "${1} " },
+    { pattern = "\\((\\w+\\s)?#([0-9]+)\\)", replace = "([#${2}](<REPO>/issues/${2}))" },
+]
+protect_breaking_commits = false
+commit_parsers = [
+    { message = "^feat", group = "<!-- 0 -->Added" },
+    { message = "^fix", group = "<!-- 1 -->Fixed" },
+    { message = "^refactor", group = "<!-- 2 -->Changed" },
+    { message = "^perf", group = "<!-- 3 -->Performance" },
+    { message = "^doc", group = "<!-- 4 -->Documentation" },
+    { message = "^test", group = "<!-- 5 -->Tests" },
+    { message = "^ci", group = "<!-- 6 -->CI" },
+    { message = "^chore\\(bot\\)", skip = true },
+    { message = "^chore\\(deps.*\\)", skip = true },
+    { message = "^chore\\(release\\):", skip = true },
+    { message = "^chore", group = "<!-- 7 -->Maintenance" },
+    { message = "^revert", group = "<!-- 8 -->Reverts" },
+    { message = ".*", group = "<!-- 9 -->Other" },
+]
+filter_commits = false
+fail_on_unmatched_commit = false
+tag_pattern = "v[0-9].*"
+link_parsers = []
+use_branch_tags = true
+topo_order = false
+topo_order_commits = true
+sort_commits = "oldest"
+
+[tool.git-cliff.bump]
+initial_tag = "v0.1.0"
+features_always_bump_minor = true
+breaking_always_bump_major = false
+no_increment_regex = "^chore|^ci|^docs?|^test"

uvg-0.1.0/src/uvg/__init__.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+try:
+    __version__ = version("uvg")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

uvg-0.1.0/src/uvg/__main__.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+
+import click
+import typer
+
+from uvg.cli import app
+from uvg.core.errors import UvgError
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Main entry point for the uvg CLI."""
+    try:
+        app(prog_name="uvg", args=argv, standalone_mode=False)
+        return 0
+    except typer.Exit as exc:
+        return exc.exit_code
+    except click.ClickException as exc:
+        exc.show(file=sys.stderr)
+        return exc.exit_code
+    except (KeyboardInterrupt, typer.Abort):
+        typer.echo("Interrupted.", err=True)
+        return 130
+    except UvgError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

uvg-0.1.0/src/uvg/cli.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import typer
+
+from uvg.commands import activate, create, init, remove
+from uvg.commands.env import app as env_app
+
+
+app = typer.Typer(
+    name="uvg",
+    help="uvg: a global virtual environment manager built on top of uv",
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+app.add_typer(create.app)
+app.add_typer(remove.app)
+app.add_typer(init.app)
+app.add_typer(activate.app)
+app.add_typer(env_app, name="env", help="Commands for managing virtual environments")

uvg-0.1.0/src/uvg/commands/__init__.py

@@ -0,0 +1 @@
+"""Command modules for the uvg CLI."""

uvg-0.1.0/src/uvg/commands/activate.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import sys
+from typing import Annotated
+
+import typer
+
+from uvg.core.environment import resolve_path
+from uvg.core.shell import (
+    ShellName,
+    get_default_shell_type_for_current_platform,
+    render_activation_command,
+)
+
+
+app = typer.Typer()
+
+
+@app.command("activate")
+def activate_environment_command(
+    environment_name: Annotated[str, typer.Argument(help="Environment name")],
+    shell_name: Annotated[
+        ShellName | None,
+        typer.Option(
+            "--shell",
+            help="Shell to generate activation code for",
+        ),
+    ] = None,
+) -> None:
+    """Generate activation command for an environment."""
+    managed_environment_path = resolve_path(environment_name)
+    resolved_shell_name = shell_name or get_default_shell_type_for_current_platform()
+    activation_command = render_activation_command(
+        managed_environment_path,
+        resolved_shell_name,
+    )
+    # Activation output is shell code consumed by eval/Invoke-Expression.
+    sys.stdout.buffer.write(f"{activation_command}\n".encode("utf-8"))

uvg-0.1.0/src/uvg/commands/create.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from uvg.core.environment import create
+
+
+app = typer.Typer()
+
+
+@app.command("create")
+def create_environment_command(
+    environment_name: Annotated[str, typer.Argument(help="Environment name")],
+    python_version: Annotated[
+        str | None,
+        typer.Option("--python", "-p", help="Python version to use, for example 3.12"),
+    ] = None,
+) -> None:
+    """Create a new managed environment."""
+    managed_environment_path = create(environment_name, python_version)
+    typer.echo(f"Created environment '{managed_environment_path.name}'")
+    typer.echo(f"Path: {managed_environment_path}")

uvg-0.1.0/src/uvg/commands/env/__init__.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import typer
+
+from uvg.commands.env import current, directory
+from uvg.commands.env import list as list_command
+
+
+app = typer.Typer(
+    name="env",
+    help="Commands for managing virtual environments",
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+app.add_typer(list_command.app)
+app.add_typer(directory.app)
+app.add_typer(current.app)

uvg-0.1.0/src/uvg/commands/env/current.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import typer
+
+from uvg.core.environment import get_current_name
+
+
+app = typer.Typer()
+
+
+@app.command("current")
+def show_current_environment_command() -> None:
+    """Show the currently active environment."""
+    active_environment_name = get_current_name()
+    typer.echo(active_environment_name)

uvg-0.1.0/src/uvg/commands/env/directory.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+import typer
+
+from uvg.core.environment import get_venvs_dir
+
+
+app = typer.Typer()
+
+
+@app.command("dir")
+def show_environment_dir_command() -> None:
+    """Show environment dir."""
+    typer.echo(get_venvs_dir())

uvg-0.1.0/src/uvg/commands/env/list.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import typer
+
+from uvg.core.environment import build_path, list_names, read_python_version
+
+
+app = typer.Typer()
+
+
+@app.command("list")
+def list_environments_command() -> None:
+    """List all managed environments."""
+    environment_names = list_names()
+    if not environment_names:
+        return
+
+    name_width = max(len(environment_name) for environment_name in environment_names)
+    for environment_name in environment_names:
+        environment_path = build_path(environment_name)
+        python_version = read_python_version(environment_path) or "unknown"
+        typer.echo(f"{environment_name:<{name_width}}  {python_version}")

uvg-0.1.0/src/uvg/commands/init.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from uvg.core.shell import (
+    IS_WINDOWS,
+    ShellName,
+    append_shell_integration_to_profile,
+    convert_windows_path_to_msys_path,
+    render_shell_integration_script,
+)
+
+
+app = typer.Typer()
+
+
+@app.command("init")
+def initialize_shell_integration_command(
+    shell_name: Annotated[ShellName, typer.Argument(help="Shell type")],
+    profile_path: Annotated[
+        Path | None,
+        typer.Option(
+            "--profile",
+            "-p",
+            help="Append the shell integration snippet to the given profile file",
+        ),
+    ] = None,
+) -> None:
+    """Initialize shell integration for uvg."""
+    if profile_path is None:
+        script_content = render_shell_integration_script(shell_name) + "\n"
+        # Shell integration output is shell code consumed by eval/Invoke-Expression.
+        sys.stdout.buffer.write(script_content.encode("utf-8"))
+        return
+
+    expanded_profile_path = profile_path.expanduser()
+    did_append_profile_snippet = append_shell_integration_to_profile(
+        shell_name,
+        expanded_profile_path,
+    )
+
+    if not did_append_profile_snippet:
+        typer.echo(f"uvg initialization is already present in {expanded_profile_path}")
+        return
+
+    expanded_profile_path_str = (
+        convert_windows_path_to_msys_path(expanded_profile_path)
+        if IS_WINDOWS
+        else str(expanded_profile_path)
+    )
+    typer.echo(
+        f"Successfully appended uvg initialization to {expanded_profile_path_str}"
+    )
+    typer.echo("Please restart your shell or source your profile to apply changes.")

uvg-0.1.0/src/uvg/commands/remove.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from uvg.core.environment import remove
+
+
+app = typer.Typer()
+
+
+@app.command("remove")
+def remove_environment_command(
+    environment_name: Annotated[str, typer.Argument(help="Environment name")],
+    assume_yes: Annotated[
+        bool,
+        typer.Option("--yes", "-y", help="Remove without confirmation"),
+    ] = False,
+) -> None:
+    """Remove a managed environment."""
+    if not assume_yes:
+        should_remove_environment = typer.confirm(
+            f"Remove environment '{environment_name}'?",
+            default=False,
+        )
+        if not should_remove_environment:
+            typer.echo("Aborted.")
+            raise typer.Exit(code=0)
+
+    remove(environment_name)
+    typer.echo(f"Removed environment '{environment_name}'")

uvg-0.1.0/src/uvg/core/environment.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import UvgError
+
+
+# ============================================================================
+# Layout
+# ============================================================================
+
+UVG_HOME_ENV_VAR = "UVG_HOME"
+DEFAULT_UVG_HOME_DIR = Path.home() / ".uvg"
+VENVS_DIR_NAME = "venvs"
+NAME_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+# ============================================================================
+# Types
+# ============================================================================
+
+
+@dataclass(frozen=True, slots=True)
+class EnvironmentInfo:
+    name: str
+    path: Path
+    python_executable: Path
+    exists: bool
+
+
+# ============================================================================
+# Layout Functions
+# ============================================================================
+
+
+def ensure_layout() -> None:
+    """Create the managed environments directory structure."""
+    get_venvs_dir().mkdir(parents=True, exist_ok=True)
+
+
+def build_path(environment_name: str) -> Path:
+    """Build the path for a managed environment."""
+    return get_venvs_dir() / environment_name
+
+
+def get_uvg_home_dir() -> Path:
+    """Return the uvg home directory."""
+    configured_home_directory = os.environ.get(UVG_HOME_ENV_VAR)
+    if configured_home_directory:
+        return Path(configured_home_directory).expanduser()
+    return DEFAULT_UVG_HOME_DIR
+
+
+def get_venvs_dir() -> Path:
+    """Return the managed environments directory."""
+    return get_uvg_home_dir() / VENVS_DIR_NAME
+
+
+def is_valid_path(path: str | Path) -> bool:
+    """Check if a path is within the managed environments directory."""
+    try:
+        resolved_path = Path(path).resolve()
+        managed_root_directory = get_venvs_dir().resolve()
+        resolved_path.relative_to(managed_root_directory)
+    except (OSError, ValueError):
+        return False
+    return True
+
+
+def extract_name_from_path(path: str | Path) -> str | None:
+    """Extract the environment name from a managed environment path."""
+    try:
+        resolved_path = Path(path).resolve()
+        managed_root_directory = get_venvs_dir().resolve()
+        relative_path = resolved_path.relative_to(managed_root_directory)
+    except (OSError, ValueError):
+        return None
+
+    return relative_path.parts[0] if relative_path.parts else None
+
+
+# ============================================================================
+# Validation
+# ============================================================================
+
+
+def validate_name(environment_name: str) -> str:
+    """Validate and normalize an environment name."""
+    normalized_environment_name = environment_name.strip()
+
+    if not normalized_environment_name:
+        raise UvgError("Environment name cannot be empty.")
+
+    if not NAME_PATTERN.fullmatch(normalized_environment_name):
+        raise UvgError(
+            "Environment name may only contain letters, numbers, dots, underscores, and hyphens."
+        )
+
+    return normalized_environment_name
+
+
+# ============================================================================
+# Runtime / Current Environment
+# ============================================================================
+
+
+def get_current_name(*, silent: bool = False) -> str | None:
+    """Get the name of the currently active managed environment."""
+    active_virtual_environment_path = os.environ.get("VIRTUAL_ENV")
+
+    if not active_virtual_environment_path:
+        if silent:
+            return None
+        raise UvgError("No active virtual environment.")
+
+    if not is_valid_path(active_virtual_environment_path):
+        if silent:
+            return None
+        raise UvgError(
+            "An active virtual environment was found, but it is not managed by uvg.\n"
+            f"Path: {active_virtual_environment_path}"
+        )
+
+    environment_name = extract_name_from_path(active_virtual_environment_path)
+    if not environment_name:
+        if silent:
+            return None
+        raise UvgError("Failed to determine current managed environment name.")
+
+    return environment_name
+
+
+# ============================================================================
+# Registry Operations
+# ============================================================================
+
+
+def list_names() -> list[str]:
+    """List all managed environment names."""
+    managed_environments_directory = get_venvs_dir()
+    if not managed_environments_directory.exists():
+        return []
+
+    environment_names = [
+        candidate_path.name
+        for candidate_path in managed_environments_directory.iterdir()
+        if candidate_path.is_dir()
+    ]
+    return sorted(environment_names)
+
+
+def resolve_path(environment_name: str) -> Path:
+    """Resolve and validate an environment path."""
+    normalized_environment_name = validate_name(environment_name)
+    managed_environment_path = build_path(normalized_environment_name)
+
+    if not managed_environment_path.exists():
+        raise UvgError(f"Environment '{normalized_environment_name}' does not exist.")
+    if not managed_environment_path.is_dir():
+        raise UvgError(
+            f"Path for environment '{normalized_environment_name}' exists but is not a directory."
+        )
+
+    return managed_environment_path
+
+
+def remove(environment_name: str) -> None:
+    """Remove a managed environment."""
+    normalized_environment_name = validate_name(environment_name)
+    managed_environment_path = resolve_path(normalized_environment_name)
+
+    if get_current_name(silent=True) == normalized_environment_name:
+        raise UvgError(
+            f"Environment '{normalized_environment_name}' is currently active. "
+            "Deactivate it before removing."
+        )
+
+    shutil.rmtree(managed_environment_path)
+
+
+# ============================================================================
+# UV Integration - Creation
+# ============================================================================
+
+
+def create(
+    environment_name: str,
+    python_version: str | None = None,
+) -> Path:
+    """Create a new managed environment using uv venv."""
+    ensure_layout()
+
+    normalized_environment_name = validate_name(environment_name)
+    managed_environment_path = build_path(normalized_environment_name)
+
+    if managed_environment_path.exists():
+        raise UvgError(f"Environment '{normalized_environment_name}' already exists.")
+
+    create_environment_command = ["uv", "venv", str(managed_environment_path), "--seed"]
+    if python_version:
+        create_environment_command.extend(["--python", python_version])
+
+    try:
+        completed_process = subprocess.run(
+            create_environment_command,
+            capture_output=True,
+            check=False,
+            text=True,
+        )
+    except FileNotFoundError as exc:
+        raise UvgError(
+            "The `uv` executable was not found. Install `uv` and ensure it is available on PATH."
+        ) from exc
+
+    if completed_process.returncode != 0:
+        standard_error_output = (completed_process.stderr or "").strip()
+        raise UvgError(
+            f"Failed to create environment '{normalized_environment_name}'."
+            + (f"\n{standard_error_output}" if standard_error_output else "")
+        )
+
+    return managed_environment_path
+
+
+def read_python_version(environment_path: Path) -> str | None:
+    """Read the Python version used by a managed environment."""
+    pyvenv_cfg_path = environment_path / "pyvenv.cfg"
+    if not pyvenv_cfg_path.exists():
+        return None
+
+    for line in pyvenv_cfg_path.read_text(encoding="utf-8").splitlines():
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        if key.strip() == "version_info":
+            return value.strip()
+    return None

uvg-0.1.0/src/uvg/core/errors.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+
+class UvgError(Exception):
+    """Raised when a uvg command cannot complete successfully."""

uvg-0.1.0/src/uvg/core/shell.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import shlex
+import sys
+from enum import Enum
+from pathlib import Path
+from typing import Literal, TypeAlias
+
+
+class ShellName(str, Enum):
+    bash = "bash"
+    zsh = "zsh"
+    pwsh = "pwsh"
+
+    @property
+    def is_posix(self) -> bool:
+        return self in {ShellName.bash, ShellName.zsh}
+
+
+PosixShellName: TypeAlias = Literal[ShellName.bash, ShellName.zsh]
+
+IS_WINDOWS = sys.platform == "win32"
+
+
+# ============================================================================
+# Constants
+# ============================================================================
+
+PROFILE_SNIPPET_START_MARKER = "# >>> uvg initialize >>>"
+PROFILE_SNIPPET_END_MARKER = "# <<< uvg initialize <<<"
+
+
+# ============================================================================
+# Shell Detection
+# ============================================================================
+
+
+def get_default_shell_type_for_current_platform() -> ShellName:
+    """Get the default shell type for the current operating system."""
+    return ShellName.pwsh if IS_WINDOWS else ShellName.bash
+
+
+# ============================================================================
+# Script Generation
+# ============================================================================
+
+
+def render_shell_integration_script(shell_name: ShellName) -> str:
+    """Render the shell integration script for a specific shell."""
+    match shell_name:
+        case ShellName.pwsh:
+            return _render_pwsh_integration_script()
+        case ShellName.bash | ShellName.zsh:
+            return _render_posix_shell_integration_script(shell_name)
+        case _:
+            raise ValueError(f"Unsupported shell: {shell_name}")
+
+
+def _render_posix_shell_integration_script(
+    shell_name: PosixShellName,
+) -> str:
+    """Render shell integration script for POSIX-style shells."""
+    return f"""# uvg shell integration for {shell_name.value}
+uvg() {{
+    if [ "$1" = "activate" ]; then
+        if [ -z "$2" ]; then
+            echo "Error: Please specify an environment name." >&2
+            return 1
+        fi
+
+        local activation_command
+        activation_command="$(command uvg activate --shell {shell_name.value} "$2")" || return 1
+        eval "$activation_command"
+        return $?
+    fi
+
+    command uvg "$@"
+}}"""
+
+
+def _render_pwsh_integration_script() -> str:
+    """Render shell integration script for Pwsh."""
+    return r"""# uvg shell integration for Pwsh
+function uvg {
+    if ($args[0] -eq "activate") {
+        if ($args.Count -lt 2 -or [string]::IsNullOrWhiteSpace($args[1])) {
+            Write-Error "Please specify an environment name."
+            $global:LASTEXITCODE = 1
+            return
+        }
+
+        $uvgExecutable = (Get-Command uvg -CommandType Application -TotalCount 1).Source
+        $activationCommand = & $uvgExecutable activate --shell pwsh $args[1]
+        if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($activationCommand)) {
+            $global:LASTEXITCODE = 1
+            return
+        }
+
+        Invoke-Expression $activationCommand
+        return
+    }
+
+    $uvgExecutable = (Get-Command uvg -CommandType Application -TotalCount 1).Source
+    & $uvgExecutable @args
+}"""
+
+
+# ============================================================================
+# Profile Integration
+# ============================================================================
+
+
+def append_shell_integration_to_profile(
+    shell_name: ShellName, profile_path: Path
+) -> bool:
+    """Append shell integration snippet to a shell profile file."""
+    initialization_command = build_profile_initialization_command(shell_name)
+    profile_snippet = render_profile_initialization_snippet(initialization_command)
+
+    if profile_path.exists():
+        current_profile_contents = profile_path.read_text(encoding="utf-8")
+        if (
+            PROFILE_SNIPPET_START_MARKER in current_profile_contents
+            or initialization_command in current_profile_contents
+        ):
+            return False
+
+    profile_path.parent.mkdir(parents=True, exist_ok=True)
+    with profile_path.open("a", encoding="utf-8", newline="\n") as profile_file:
+        profile_file.write(profile_snippet)
+
+    return True
+
+
+def build_profile_initialization_command(shell_name: ShellName) -> str:
+    """Build the initialization command for a shell profile."""
+    match shell_name:
+        case ShellName.pwsh:
+            return "Invoke-Expression (uvg init pwsh | Out-String)"
+        case ShellName.bash:
+            return 'eval "$(uvg init bash)"'
+        case ShellName.zsh:
+            return 'eval "$(uvg init zsh)"'
+        case _:
+            raise ValueError(f"Unsupported shell: {shell_name}")
+
+
+def render_profile_initialization_snippet(initialization_command: str) -> str:
+    """Render the profile initialization snippet with markers."""
+    return (
+        "\n"
+        f"{PROFILE_SNIPPET_START_MARKER}\n"
+        f"{initialization_command}\n"
+        f"{PROFILE_SNIPPET_END_MARKER}\n"
+    )
+
+
+# ============================================================================
+# Activation
+# ============================================================================
+
+
+def render_activation_command(environment_path: Path, shell_name: ShellName) -> str:
+    """Render the command to activate an environment for a specific shell."""
+    activation_script_path = build_activation_script_path(environment_path, shell_name)
+
+    if shell_name in {ShellName.bash, ShellName.zsh}:
+        return f"source {shlex.quote(activation_script_path)}"
+
+    return f". {_quote_pwsh_string_literal(activation_script_path)}"
+
+
+def build_activation_script_path(environment_path: Path, shell_name: ShellName) -> str:
+    """Build the path to the activation script for a shell."""
+    scripts_dir = environment_path / ("Scripts" if IS_WINDOWS else "bin")
+
+    if shell_name in {ShellName.bash, ShellName.zsh}:
+        script_path = scripts_dir / "activate"
+        return (
+            convert_windows_path_to_msys_path(script_path)
+            if IS_WINDOWS
+            else str(script_path)
+        )
+
+    return str(scripts_dir / "Activate.ps1")
+
+
+def _quote_pwsh_string_literal(value: str) -> str:
+    """Quote a string for Pwsh."""
+    return "'" + value.replace("'", "''") + "'"
+
+
+def convert_windows_path_to_msys_path(path: Path) -> str:
+    """Convert C:/style paths to /c/style paths for MSYS-like shells."""
+    posix_path = path.as_posix()
+    if len(posix_path) >= 3 and posix_path[1:3] == ":/":
+        return f"/{posix_path[0].lower()}{posix_path[2:]}"
+    return posix_path