bitp 1.0.6__py3-none-any.whl

bitbake_project/core.py

@@ -0,0 +1,1811 @@
+#
+# Copyright (C) 2025 Bruce Ashfield <bruce.ashfield@gmail.com>
+#
+# SPDX-License-Identifier: GPL-2.0-only
+#
+"""
+Core abstractions for bit.
+
+This module provides:
+- Colors: ANSI color formatting
+- GitRepo: Git repository operations wrapper
+- FzfMenu: fzf menu builder and runner
+- State management: defaults, prep state, export state
+"""
+
+import json
+import os
+import shutil
+import subprocess
+from datetime import datetime
+from typing import Callable, Dict, List, Optional, Set, Tuple, Union
+
+
+class Colors:
+    """ANSI color codes for terminal output."""
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    RED = "\033[31m"
+    CYAN = "\033[36m"
+    MAGENTA = "\033[35m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    RESET = "\033[0m"
+
+    @classmethod
+    def green(cls, text: str) -> str:
+        return f"{cls.GREEN}{text}{cls.RESET}"
+
+    @classmethod
+    def yellow(cls, text: str) -> str:
+        return f"{cls.YELLOW}{text}{cls.RESET}"
+
+    @classmethod
+    def red(cls, text: str) -> str:
+        return f"{cls.RED}{text}{cls.RESET}"
+
+    @classmethod
+    def cyan(cls, text: str) -> str:
+        return f"{cls.CYAN}{text}{cls.RESET}"
+
+    @classmethod
+    def magenta(cls, text: str) -> str:
+        return f"{cls.MAGENTA}{text}{cls.RESET}"
+
+    @classmethod
+    def dim(cls, text: str) -> str:
+        return f"{cls.DIM}{text}{cls.RESET}"
+
+    @classmethod
+    def bold(cls, text: str) -> str:
+        return f"{cls.BOLD}{text}{cls.RESET}"
+
+
+# =============================================================================
+# FZF Themes
+# =============================================================================
+
+# Theme format: fzf --color option string
+# Themes control: fg+/bg+ (current line), hl/hl+ (match highlight),
+#                 pointer, marker, prompt, header, info
+# Note: fg (default text) is a separate setting to allow independent control
+FZF_THEMES: Dict[str, Tuple[str, str]] = {
+    # (color_string, description)
+    "default": (
+        "",
+        "Terminal default colors"
+    ),
+    "dark": (
+        "fg+:white,bg+:236,hl:yellow,hl+:yellow,pointer:cyan,marker:cyan,prompt:cyan,header:blue",
+        "Dark background optimized"
+    ),
+    "light": (
+        "fg+:black,bg+:254,hl:blue,hl+:blue,pointer:magenta,marker:magenta,prompt:magenta,header:blue",
+        "Light background optimized"
+    ),
+    "high-contrast": (
+        "fg+:white:bold,bg+:black,hl:yellow:bold,hl+:yellow:bold,pointer:red:bold,marker:red:bold,prompt:green:bold,header:cyan:bold",
+        "Maximum visibility"
+    ),
+    "ocean": (
+        "fg+:white,bg+:24,hl:cyan,hl+:cyan:bold,pointer:white,marker:white,prompt:cyan,header:39",
+        "Blue ocean tones"
+    ),
+    "forest": (
+        "fg+:white,bg+:22,hl:yellow,hl+:yellow:bold,pointer:white,marker:white,prompt:green,header:34",
+        "Green forest tones"
+    ),
+    "nord": (
+        "fg+:white,bg+:60,hl:cyan,hl+:cyan:bold,pointer:cyan,marker:cyan,prompt:blue,header:blue",
+        "Nord color scheme"
+    ),
+    "dracula": (
+        "fg+:white,bg+:61,hl:212,hl+:212:bold,pointer:212,marker:212,prompt:141,header:139",
+        "Dracula color scheme"
+    ),
+}
+
+# Text color presets (fg) - separate from themes for independent control
+# Use these if your terminal's default text color doesn't work well
+FZF_TEXT_COLORS: Dict[str, Tuple[str, str]] = {
+    # (fg_color_value, description)
+    "auto": ("", "Use terminal default"),
+    "white": ("white", "White text (for dark backgrounds)"),
+    "light-gray": ("252", "Light gray (for dark backgrounds)"),
+    "dark-gray": ("235", "Dark gray (for light backgrounds)"),
+    "black": ("black", "Black text (for light backgrounds)"),
+    "green": ("green", "Green text"),
+    "cyan": ("cyan", "Cyan text"),
+    "yellow": ("yellow", "Yellow text"),
+}
+
+# Individual color elements that can be customized
+# These override theme settings for specific elements
+FZF_COLOR_ELEMENTS: Dict[str, str] = {
+    # element_name: description
+    "fg": "Default text",
+    "fg+": "Current line text",
+    "bg+": "Current line background",
+    "hl": "Match highlight",
+    "hl+": "Match highlight (current line)",
+    "pointer": "Pointer arrow",
+    "marker": "Multi-select marker",
+    "prompt": "Prompt text",
+    "header": "Header text",
+    "info": "Info line",
+}
+
+# Color values available for individual customization
+COLOR_VALUES: Dict[str, str] = {
+    # name: fzf color value
+    "(default)": "",
+    "white": "white",
+    "black": "black",
+    "red": "red",
+    "green": "green",
+    "yellow": "yellow",
+    "blue": "blue",
+    "magenta": "magenta",
+    "cyan": "cyan",
+    # 256-color values
+    "light-gray": "252",
+    "dark-gray": "236",
+    "light-red": "203",
+    "light-green": "114",
+    "light-yellow": "228",
+    "light-blue": "75",
+    "light-magenta": "213",
+    "light-cyan": "123",
+    "orange": "208",
+    "pink": "212",
+    "purple": "141",
+    "teal": "37",
+}
+
+# =============================================================================
+# Terminal Output Colors (configurable)
+# =============================================================================
+
+# Elements in terminal output that can have their color customized
+TERMINAL_COLOR_ELEMENTS: Dict[str, Tuple[str, str]] = {
+    # element_name: (default_color, description)
+    "upstream": ("yellow", "Upstream commit indicator (↓ N to pull)"),
+    "local": ("green", "Local commit count"),
+    "dirty": ("red", "Dirty working tree indicator"),
+    "clean": ("green", "Clean working tree indicator"),
+    "repo": ("green", "Repo name (configured layers)"),
+    "repo_discovered": ("magenta", "Repo name (discovered layers)"),
+    "repo_external": ("cyan", "Repo name (external repos)"),
+    "fragment_enabled": ("green", "Enabled fragment in browser"),
+}
+
+# ANSI codes for terminal colors
+ANSI_COLORS: Dict[str, str] = {
+    "white": "\033[37m",
+    "black": "\033[30m",
+    "red": "\033[31m",
+    "green": "\033[32m",
+    "yellow": "\033[33m",
+    "blue": "\033[34m",
+    "magenta": "\033[35m",
+    "cyan": "\033[36m",
+    # Bright/light variants (using 256-color codes)
+    "light-gray": "\033[38;5;252m",
+    "dark-gray": "\033[38;5;236m",
+    "light-red": "\033[38;5;203m",
+    "light-green": "\033[38;5;114m",
+    "light-yellow": "\033[38;5;228m",
+    "light-blue": "\033[38;5;75m",
+    "light-magenta": "\033[38;5;213m",
+    "light-cyan": "\033[38;5;123m",
+    "orange": "\033[38;5;208m",
+    "pink": "\033[38;5;212m",
+    "purple": "\033[38;5;141m",
+    "teal": "\033[38;5;37m",
+}
+
+
+def get_terminal_color(element: str, defaults_file: str = ".bit.defaults") -> str:
+    """
+    Get configured color for a terminal output element.
+
+    Args:
+        element: Element name from TERMINAL_COLOR_ELEMENTS
+        defaults_file: Path to defaults file
+
+    Returns:
+        Color name (e.g., "yellow", "cyan")
+    """
+    # Get default for this element
+    default_color = TERMINAL_COLOR_ELEMENTS.get(element, ("yellow", ""))[0]
+
+    try:
+        if os.path.exists(defaults_file):
+            with open(defaults_file, encoding="utf-8") as f:
+                data = json.load(f)
+            terminal_colors = data.get("terminal_colors", {})
+            return terminal_colors.get(element, default_color)
+    except (json.JSONDecodeError, OSError):
+        pass
+    return default_color
+
+
+def set_terminal_color(element: str, color_name: str, defaults_file: str = ".bit.defaults") -> bool:
+    """
+    Set color for a terminal output element.
+
+    Args:
+        element: Element name from TERMINAL_COLOR_ELEMENTS
+        color_name: Color name from ANSI_COLORS
+        defaults_file: Path to defaults file
+
+    Returns:
+        True if successful
+    """
+    if element not in TERMINAL_COLOR_ELEMENTS:
+        return False
+    if color_name not in ANSI_COLORS and color_name != "(default)":
+        return False
+
+    try:
+        data = {}
+        if os.path.exists(defaults_file):
+            with open(defaults_file, encoding="utf-8") as f:
+                data = json.load(f)
+
+        if "terminal_colors" not in data:
+            data["terminal_colors"] = {}
+
+        default_color = TERMINAL_COLOR_ELEMENTS[element][0]
+        if color_name == "(default)" or color_name == default_color:
+            # Remove custom setting, use default
+            data["terminal_colors"].pop(element, None)
+        else:
+            data["terminal_colors"][element] = color_name
+
+        # Clean up empty dict
+        if not data["terminal_colors"]:
+            del data["terminal_colors"]
+
+        with open(defaults_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+        return True
+    except (OSError, json.JSONDecodeError):
+        return False
+
+
+def terminal_color(element: str, text: str, defaults_file: str = ".bit.defaults") -> str:
+    """
+    Apply configured terminal color to text.
+
+    Args:
+        element: Element name from TERMINAL_COLOR_ELEMENTS
+        text: Text to colorize
+        defaults_file: Path to defaults file
+
+    Returns:
+        Colorized text string with ANSI codes
+    """
+    color_name = get_terminal_color(element, defaults_file)
+    ansi_code = ANSI_COLORS.get(color_name, ANSI_COLORS.get("yellow", "\033[33m"))
+    return f"{ansi_code}{text}\033[0m"
+
+
+def get_fzf_theme(defaults_file: str = ".bit.defaults") -> str:
+    """
+    Get the current fzf theme color string from defaults.
+
+    Returns:
+        fzf --color option string, or empty string for default.
+    """
+    try:
+        if os.path.exists(defaults_file):
+            with open(defaults_file, encoding="utf-8") as f:
+                data = json.load(f)
+            theme_name = data.get("fzf_theme", "default")
+            if theme_name in FZF_THEMES:
+                return FZF_THEMES[theme_name][0]
+    except (json.JSONDecodeError, OSError):
+        pass
+    return ""
+
+
+def get_fzf_text_color(defaults_file: str = ".bit.defaults") -> str:
+    """
+    Get the current fzf text color (fg) setting from defaults.
+
+    Returns:
+        fg color value (e.g., "white", "252") or empty string for auto/default.
+    """
+    try:
+        if os.path.exists(defaults_file):
+            with open(defaults_file, encoding="utf-8") as f:
+                data = json.load(f)
+            color_name = data.get("fzf_text_color", "auto")
+            if color_name in FZF_TEXT_COLORS:
+                return FZF_TEXT_COLORS[color_name][0]
+    except (json.JSONDecodeError, OSError):
+        pass
+    return ""
+
+
+def set_fzf_text_color(color_name: str, defaults_file: str = ".bit.defaults") -> bool:
+    """
+    Save fzf text color setting to defaults file.
+
+    Returns:
+        True if successful, False otherwise.
+    """
+    if color_name not in FZF_TEXT_COLORS:
+        return False
+
+    try:
+        data = {}
+        if os.path.exists(defaults_file):
+            with open(defaults_file, encoding="utf-8") as f:
+                data = json.load(f)
+
+        data["fzf_text_color"] = color_name
+
+        with open(defaults_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+        return True
+    except (json.JSONDecodeError, OSError):
+        return False
+
+
+def get_current_text_color_name(defaults_file: str = ".bit.defaults") -> str:
+    """Get the current text color setting name (not the value)."""
+    try:
+        if os.path.exists(defaults_file):
+            with open(defaults_file, encoding="utf-8") as f:
+                data = json.load(f)
+            return data.get("fzf_text_color", "auto")
+    except (json.JSONDecodeError, OSError):
+        pass
+    return "auto"
+
+
+def get_custom_colors(defaults_file: str = ".bit.defaults") -> Dict[str, str]:
+    """
+    Get individual color overrides from defaults.
+
+    Returns:
+        Dict mapping element names to color values, e.g. {"pointer": "green", "header": "white"}
+    """
+    try:
+        if os.path.exists(defaults_file):
+            with open(defaults_file, encoding="utf-8") as f:
+                data = json.load(f)
+            return data.get("fzf_custom_colors", {})
+    except (json.JSONDecodeError, OSError):
+        pass
+    return {}
+
+
+def set_custom_color(element: str, color_name: str, defaults_file: str = ".bit.defaults") -> bool:
+    """
+    Set an individual color override.
+
+    Args:
+        element: Color element (e.g., "pointer", "header")
+        color_name: Color name from COLOR_VALUES (e.g., "green", "(default)")
+
+    Returns:
+        True if successful
+    """
+    if element not in FZF_COLOR_ELEMENTS:
+        return False
+    if color_name not in COLOR_VALUES:
+        return False
+
+    try:
+        data = {}
+        if os.path.exists(defaults_file):
+            with open(defaults_file, encoding="utf-8") as f:
+                data = json.load(f)
+
+        if "fzf_custom_colors" not in data:
+            data["fzf_custom_colors"] = {}
+
+        if color_name == "(default)":
+            # Remove the override
+            data["fzf_custom_colors"].pop(element, None)
+        else:
+            data["fzf_custom_colors"][element] = color_name
+
+        # Clean up empty dict
+        if not data["fzf_custom_colors"]:
+            del data["fzf_custom_colors"]
+
+        with open(defaults_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+        return True
+    except (json.JSONDecodeError, OSError):
+        return False
+
+
+def clear_custom_colors(defaults_file: str = ".bit.defaults") -> bool:
+    """Clear all individual color overrides."""
+    try:
+        data = {}
+        if os.path.exists(defaults_file):
+            with open(defaults_file, encoding="utf-8") as f:
+                data = json.load(f)
+
+        data.pop("fzf_custom_colors", None)
+
+        with open(defaults_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+        return True
+    except (json.JSONDecodeError, OSError):
+        return False
+
+
+def get_fzf_color_args(defaults_file: str = ".bit.defaults") -> List[str]:
+    """
+    Get fzf --color arguments as a list for subprocess calls.
+
+    Combines theme colors with individual overrides (custom colors take precedence).
+
+    Returns:
+        List like ["--color", "fg:white,fg+:white,bg+:blue,..."] or empty list for default.
+    """
+    theme_colors = get_fzf_theme(defaults_file)
+    text_color = get_fzf_text_color(defaults_file)
+    custom_colors = get_custom_colors(defaults_file)
+
+    # Build combined color string
+    color_parts = []
+
+    # 1. Theme colors (base)
+    if theme_colors:
+        color_parts.append(theme_colors)
+
+    # 2. Text color override (fg from separate setting)
+    if text_color:
+        color_parts.append(f"fg:{text_color}")
+
+    # 3. Individual custom color overrides (highest precedence)
+    for element, color_name in custom_colors.items():
+        if color_name in COLOR_VALUES and COLOR_VALUES[color_name]:
+            color_parts.append(f"{element}:{COLOR_VALUES[color_name]}")
+
+    if color_parts:
+        return ["--color", ",".join(color_parts)]
+    return []
+
+
+def get_fzf_preview_resize_bindings(start_size: int = 50) -> List[str]:
+    """
+    Generate fzf keybindings for preview window resize with coordinated state.
+
+    Uses fzf's --listen HTTP API to send resize commands. State is tracked
+    in a temp file so alt-right and alt-left coordinate properly.
+
+    Args:
+        start_size: Initial preview window percentage (default 50)
+
+    Returns:
+        List of fzf arguments including --listen and resize bindings
+    """
+    # Check if curl is available for HTTP API approach
+    if not shutil.which("curl"):
+        # Fallback to simple cycling if no curl
+        return [
+            "--bind", "alt-p:change-preview-window(50%|40%|30%|20%|10%|hidden|90%|80%|70%|60%)",
+        ]
+
+    # Generate a unique port based on PID + random to avoid collisions
+    import random
+    port = 10000 + (os.getpid() % 10000) + random.randint(0, 999)
+
+    # State file unique to this fzf instance
+    state_file = f"/tmp/fzf-pw-{port}"
+
+    # Initialize state file with starting size
+    try:
+        with open(state_file, "w") as f:
+            f.write(str(start_size))
+    except OSError:
+        # Fall back to simple cycling if we can't write state
+        return [
+            "--bind", "alt-p:change-preview-window(50%|40%|30%|20%|10%|hidden|90%|80%|70%|60%)",
+        ]
+
+    # Inline bash commands for resize (no external script needed)
+    # Reads state, adjusts, writes back, posts to fzf HTTP API
+    shrink_cmd = (
+        f"s=$(cat {state_file} 2>/dev/null||echo 50);"
+        f"s=$((s-10));[ $s -lt 10 ]&&s=10;"
+        f"echo $s>{state_file};"
+        f"curl -s -XPOST localhost:{port} -d change-preview-window:$s% >/dev/null 2>&1"
+    )
+    grow_cmd = (
+        f"s=$(cat {state_file} 2>/dev/null||echo 50);"
+        f"s=$((s+10));[ $s -gt 90 ]&&s=90;"
+        f"echo $s>{state_file};"
+        f"curl -s -XPOST localhost:{port} -d change-preview-window:$s% >/dev/null 2>&1"
+    )
+
+    return [
+        "--listen", str(port),
+        "--bind", f"alt-right:execute-silent({shrink_cmd})",
+        "--bind", f"alt-left:execute-silent({grow_cmd})",
+    ]
+
+
+def run_fzf(
+    args: List[str],
+    input_text: Optional[str] = None,
+    defaults_file: str = ".bit.defaults",
+) -> subprocess.CompletedProcess:
+    """
+    Run fzf with automatic theme color support.
+
+    This is the preferred way to run fzf - it automatically applies
+    the user's configured theme colors.
+
+    Args:
+        args: fzf arguments (should NOT include "fzf" as first element,
+              but if it does, it will be handled)
+        input_text: Optional text to pass to fzf's stdin
+        defaults_file: Path to defaults file for theme lookup
+
+    Returns:
+        subprocess.CompletedProcess with stdout captured as text.
+
+    Raises:
+        FileNotFoundError: If fzf is not installed.
+
+    Example:
+        result = run_fzf(
+            ["--no-multi", "--height", "50%", "--header", "Pick one"],
+            input_text="option1\\noption2\\noption3"
+        )
+        if result.returncode == 0:
+            selected = result.stdout.strip()
+    """
+    # Normalize args - ensure "fzf" is first
+    if args and args[0] != "fzf":
+        args = ["fzf"] + args
+    elif not args:
+        args = ["fzf"]
+
+    # Add theme colors
+    color_args = get_fzf_color_args(defaults_file)
+    if color_args:
+        args = args + color_args
+
+    return subprocess.run(
+        args,
+        input=input_text,
+        stdout=subprocess.PIPE,
+        text=True,
+    )
+
+
+def set_fzf_theme(theme_name: str, defaults_file: str = ".bit.defaults") -> bool:
+    """
+    Save fzf theme to defaults file.
+
+    Args:
+        theme_name: Name of theme from FZF_THEMES
+        defaults_file: Path to defaults file
+
+    Returns:
+        True if saved successfully
+    """
+    if theme_name not in FZF_THEMES:
+        return False
+
+    try:
+        data = {}
+        if os.path.exists(defaults_file):
+            with open(defaults_file, encoding="utf-8") as f:
+                data = json.load(f)
+
+        data["fzf_theme"] = theme_name
+
+        with open(defaults_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+        return True
+    except (json.JSONDecodeError, OSError):
+        return False
+
+
+def get_current_theme_name(defaults_file: str = ".bit.defaults") -> str:
+    """Get the name of the currently selected theme."""
+    try:
+        if os.path.exists(defaults_file):
+            with open(defaults_file, encoding="utf-8") as f:
+                data = json.load(f)
+            theme_name = data.get("fzf_theme", "default")
+            if theme_name in FZF_THEMES:
+                return theme_name
+    except (json.JSONDecodeError, OSError):
+        pass
+    return "default"
+
+
+def fzf_theme_picker(defaults_file: str = ".bit.defaults") -> Optional[str]:
+    """
+    Show fzf menu to select a color theme.
+
+    The menu shows a live preview of each theme's colors and loops
+    so the user can see the effect before exiting.
+
+    Args:
+        defaults_file: Path to defaults file for saving selection
+
+    Returns:
+        Selected theme name, or None if cancelled.
+    """
+    if not fzf_available():
+        return None
+
+    last_selected = None
+
+    while True:
+        current_theme = get_current_theme_name(defaults_file)
+
+        # Build menu with theme previews
+        menu_lines = []
+        for name, (colors, description) in FZF_THEMES.items():
+            marker = "● " if name == current_theme else "  "
+            # Color the theme name based on what it would look like
+            colored_name = f"\033[36m{name:<15}\033[0m"
+            menu_lines.append(f"{name}\t{marker}{colored_name}  {description}")
+
+        menu_input = "\n".join(menu_lines)
+
+        # Build preview content showing all elements with current colors
+        preview_content = _build_color_preview(defaults_file)
+        preview_escaped = preview_content.replace("'", "'\\''")
+        preview_cmd = f"echo '{preview_escaped}'"
+
+        # Build fzf command
+        fzf_args = [
+            "fzf",
+            "--no-multi",
+            "--no-sort",
+            "--no-info",
+            "--ansi",
+            "--height", "20",
+            "--layout", "reverse",
+            "--header", "Select theme (Enter to apply, ←/q=back)",
+            "--prompt", "Theme: ",
+            "--with-nth", "2..",
+            "--delimiter", "\t",
+            "--bind", "q:abort",
+            "--bind", "left:abort",
+            "--preview", preview_cmd,
+            "--preview-window", "right:60%:noborder",
+        ]
+
+        # Apply preview resize and theme colors
+        fzf_args.extend(get_fzf_preview_resize_bindings())
+        fzf_args.extend(get_fzf_color_args(defaults_file))
+
+        try:
+            result = subprocess.run(
+                fzf_args,
+                input=menu_input,
+                stdout=subprocess.PIPE,
+                text=True,
+            )
+        except FileNotFoundError:
+            return last_selected
+
+        if result.returncode != 0 or not result.stdout.strip():
+            return last_selected
+
+        selected = result.stdout.strip().split("\t")[0]
+
+        if selected in FZF_THEMES:
+            set_fzf_theme(selected, defaults_file)
+            last_selected = selected
+            # Loop to show updated preview
+
+
+def fzf_text_color_picker(defaults_file: str = ".bit.defaults") -> Optional[str]:
+    """
+    Show fzf menu to select text color (fg).
+
+    Args:
+        defaults_file: Path to defaults file for saving selection
+
+    Returns:
+        Selected color name, or None if cancelled.
+    """
+    if not fzf_available():
+        return None
+
+    current_color = get_current_text_color_name(defaults_file)
+
+    # Build menu
+    menu_lines = []
+    for name, (color_value, description) in FZF_TEXT_COLORS.items():
+        marker = "● " if name == current_color else "  "
+        # Show a sample of the color if it's set
+        if color_value:
+            sample = f"\033[38;5;{color_value}m■■■\033[0m" if color_value.isdigit() else f"\033[{'37' if color_value == 'white' else '30' if color_value == 'black' else '32' if color_value == 'green' else '36' if color_value == 'cyan' else '33' if color_value == 'yellow' else '37'}m■■■\033[0m"
+        else:
+            sample = "   "
+        menu_lines.append(f"{name}\t{marker}{name:<12} {sample}  {description}")
+
+    menu_input = "\n".join(menu_lines)
+
+    fzf_args = [
+        "fzf",
+        "--no-multi",
+        "--no-sort",
+        "--no-info",
+        "--ansi",
+        "--height", "~50%",
+        "--header", "Select text color (Enter to apply, q to cancel)",
+        "--prompt", "Color: ",
+        "--with-nth", "2..",
+        "--delimiter", "\t",
+        "--bind", "q:abort",
+    ]
+
+    # Apply current colors
+    fzf_args.extend(get_fzf_color_args(defaults_file))
+
+    try:
+        result = subprocess.run(
+            fzf_args,
+            input=menu_input,
+            stdout=subprocess.PIPE,
+            text=True,
+        )
+    except FileNotFoundError:
+        return None
+
+    if result.returncode != 0 or not result.stdout.strip():
+        return None
+
+    selected = result.stdout.strip().split("\t")[0]
+
+    if selected in FZF_TEXT_COLORS:
+        set_fzf_text_color(selected, defaults_file)
+        return selected
+
+    return None
+
+
+def _build_color_preview(defaults_file: str) -> str:
+    """Build a preview showing all color elements with current settings."""
+    # Get current effective colors (theme + custom overrides)
+    theme_colors = get_fzf_theme(defaults_file)
+    custom_colors = get_custom_colors(defaults_file)
+
+    # Parse theme colors into a dict
+    effective = {}
+    if theme_colors:
+        for part in theme_colors.split(","):
+            if ":" in part:
+                key, val = part.split(":", 1)
+                effective[key] = val
+
+    # Apply custom overrides
+    for element, color_name in custom_colors.items():
+        if color_name in COLOR_VALUES and COLOR_VALUES[color_name]:
+            effective[element] = COLOR_VALUES[color_name]
+
+    def ansi(color_val: str, text: str) -> str:
+        """Wrap text in ANSI color codes."""
+        if not color_val:
+            return text
+        fg_codes = {"white": "37", "black": "30", "red": "31", "green": "32",
+                    "yellow": "33", "blue": "34", "magenta": "35", "cyan": "36"}
+        if color_val in fg_codes:
+            return f"\033[{fg_codes[color_val]}m{text}\033[0m"
+        elif color_val.isdigit():
+            return f"\033[38;5;{color_val}m{text}\033[0m"
+        return text
+
+    def combo(fg_val: str, bg_val: str, text: str) -> str:
+        """Combine fg and bg colors."""
+        fg_codes = {"white": "37", "black": "30", "red": "31", "green": "32",
+                    "yellow": "33", "blue": "34", "magenta": "35", "cyan": "36"}
+        bg_codes = {"white": "47", "black": "40", "red": "41", "green": "42",
+                    "yellow": "43", "blue": "44", "magenta": "45", "cyan": "46"}
+        codes = []
+        if fg_val:
+            if fg_val in fg_codes:
+                codes.append(fg_codes[fg_val])
+            elif fg_val.isdigit():
+                codes.append(f"38;5;{fg_val}")
+        if bg_val:
+            if bg_val in bg_codes:
+                codes.append(bg_codes[bg_val])
+            elif bg_val.isdigit():
+                codes.append(f"48;5;{bg_val}")
+        if codes:
+            return f"\033[{';'.join(codes)}m{text}\033[0m"
+        return text
+
+    W = 28  # Inner content width
+
+    def pad(text: str, visible_len: int) -> str:
+        """Pad text to fill the box width."""
+        return text + " " * (W - visible_len)
+
+    def row(content: str, visible_len: int) -> str:
+        """Create a box row."""
+        return f"│ {pad(content, visible_len)} │"
+
+    # Build preview lines
+    lines = ["┌" + "─" * W + "──┐"]
+
+    # Pointer and marker
+    ptr = effective.get("pointer", "")
+    mkr = effective.get("marker", "")
+    lines.append(row(f"{ansi(ptr, '>')} item one", 10))
+    lines.append(row(f"{ansi(mkr, '●')} item two (marked)", 19))
+    lines.append(row("", 0))
+
+    # Prompt
+    pmt = effective.get("prompt", "")
+    lines.append(row(f"{ansi(pmt, 'prompt:')} type here", 17))
+
+    # Header
+    hdr = effective.get("header", "")
+    lines.append(row(ansi(hdr, "Header: ? for help"), 18))
+    lines.append(row("", 0))
+
+    # Normal text (fg)
+    fg = effective.get("fg", "")
+    lines.append(row(ansi(fg, "Normal text (fg)"), 16))
+
+    # Highlight
+    hl = effective.get("hl", "")
+    lines.append(row(f"Search {ansi(hl, 'match')} here", 17))
+    lines.append(row("", 0))
+
+    # Selected line (fg+ on bg+)
+    fg_plus = effective.get("fg+", "")
+    bg_plus = effective.get("bg+", "")
+    hl_plus = effective.get("hl+", "")
+    sel_text = f"Selected {ansi(hl_plus, 'match')} line"
+    sel_padded = pad(sel_text, 19)
+    lines.append(f"│ {combo(fg_plus, bg_plus, sel_padded)} │")
+
+    # Info
+    inf = effective.get("info", "")
+    lines.append(row(ansi(inf, "info: 5/10"), 10))
+
+    lines.append("└" + "─" * W + "──┘")
+
+    return "\n".join(lines)
+
+
+def fzf_custom_color_menu(defaults_file: str = ".bit.defaults") -> None:
+    """
+    Show fzf menu to customize individual color elements.
+
+    Presents a list of color elements (pointer, header, etc.) and lets
+    user pick which one to customize.
+    """
+    if not fzf_available():
+        return
+
+    while True:
+        custom_colors = get_custom_colors(defaults_file)
+        override_count = len(custom_colors)
+
+        # Build menu of elements
+        menu_lines = []
+        for element, description in FZF_COLOR_ELEMENTS.items():
+            current = custom_colors.get(element, "(default)")
+            # Show color sample
+            if current != "(default)" and current in COLOR_VALUES:
+                color_val = COLOR_VALUES[current]
+                if color_val:
+                    sample = _color_sample(color_val)
+                else:
+                    sample = "   "
+            else:
+                sample = "   "
+            menu_lines.append(f"{element}\t{element:<10} {sample} {current:<14} {description}")
+
+        # Add separator and reset option
+        menu_lines.append(f"---\t{'─' * 50}")
+        if override_count > 0:
+            menu_lines.append(f"CLEAR\t✖ Reset all ({override_count} override{'s' if override_count != 1 else ''}) — restore theme defaults")
+        else:
+            menu_lines.append(f"CLEAR\t  (no overrides)")
+
+        menu_input = "\n".join(menu_lines)
+
+        # Build preview content showing all elements with current colors
+        preview_content = _build_color_preview(defaults_file)
+        # Escape for shell
+        preview_escaped = preview_content.replace("'", "'\\''")
+        preview_cmd = f"echo '{preview_escaped}'"
+
+        fzf_args = [
+            "fzf",
+            "--no-multi",
+            "--no-sort",
+            "--no-info",
+            "--ansi",
+            "--height", "20",
+            "--layout", "reverse",
+            "--header", "Individual Colors (Enter=edit, ←/q=back)",
+            "--prompt", "Element: ",
+            "--with-nth", "2..",
+            "--delimiter", "\t",
+            "--bind", "q:abort",
+            "--bind", "left:abort",
+            "--preview", preview_cmd,
+            "--preview-window", "right:60%:noborder",
+        ]
+
+        fzf_args.extend(get_fzf_preview_resize_bindings())
+        fzf_args.extend(get_fzf_color_args(defaults_file))
+
+        try:
+            result = subprocess.run(
+                fzf_args,
+                input=menu_input,
+                stdout=subprocess.PIPE,
+                text=True,
+            )
+        except FileNotFoundError:
+            return
+
+        if result.returncode != 0 or not result.stdout.strip():
+            return
+
+        selected = result.stdout.strip().split("\t")[0]
+
+        if selected == "CLEAR":
+            clear_custom_colors(defaults_file)
+        elif selected == "---":
+            pass  # Separator, do nothing
+        elif selected in FZF_COLOR_ELEMENTS:
+            _pick_color_for_element(selected, defaults_file)
+
+
+def _color_sample(color_val: str) -> str:
+    """Generate ANSI color sample for a color value."""
+    if not color_val:
+        return "   "
+    # Map named colors to ANSI codes
+    named_colors = {
+        "white": "37", "black": "30", "red": "31", "green": "32",
+        "yellow": "33", "blue": "34", "magenta": "35", "cyan": "36",
+    }
+    if color_val in named_colors:
+        return f"\033[{named_colors[color_val]}m■■■\033[0m"
+    elif color_val.isdigit():
+        return f"\033[38;5;{color_val}m■■■\033[0m"
+    return "■■■"
+
+
+def _pick_color_for_element(element: str, defaults_file: str) -> Optional[str]:
+    """Show color picker for a specific element."""
+    if not fzf_available():
+        return None
+
+    custom_colors = get_custom_colors(defaults_file)
+    current = custom_colors.get(element, "(default)")
+
+    # Build menu of colors
+    menu_lines = []
+    for name, value in COLOR_VALUES.items():
+        marker = "● " if name == current else "  "
+        sample = _color_sample(value) if value else "   "
+        menu_lines.append(f"{name}\t{marker}{name:<14} {sample}")
+
+    menu_input = "\n".join(menu_lines)
+
+    # Build preview showing what changing this element would look like
+    preview_content = _build_color_preview(defaults_file)
+    preview_escaped = preview_content.replace("'", "'\\''")
+    preview_cmd = f"echo '{preview_escaped}'"
+
+    desc = FZF_COLOR_ELEMENTS.get(element, element)
+    fzf_args = [
+        "fzf",
+        "--no-multi",
+        "--no-sort",
+        "--no-info",
+        "--ansi",
+        "--height", "20",
+        "--layout", "reverse",
+        "--header", f"Select color for {element} ({desc}) ←/q=back",
+        "--prompt", "Color: ",
+        "--with-nth", "2..",
+        "--delimiter", "\t",
+        "--bind", "q:abort",
+        "--bind", "left:abort",
+        "--preview", preview_cmd,
+        "--preview-window", "right:60%:noborder",
+    ]
+
+    fzf_args.extend(get_fzf_preview_resize_bindings())
+    fzf_args.extend(get_fzf_color_args(defaults_file))
+
+    try:
+        result = subprocess.run(
+            fzf_args,
+            input=menu_input,
+            stdout=subprocess.PIPE,
+            text=True,
+        )
+    except FileNotFoundError:
+        return None
+
+    if result.returncode != 0 or not result.stdout.strip():
+        return None
+
+    selected = result.stdout.strip().split("\t")[0]
+
+    if selected in COLOR_VALUES:
+        set_custom_color(element, selected, defaults_file)
+        return selected
+
+    return None
+
+
+class GitRepo:
+    """
+    Git repository wrapper providing consistent interface for git operations.
+
+    Usage:
+        repo = GitRepo("/path/to/repo")
+        branch = repo.current_branch()
+        if repo.is_clean():
+            repo.run(["pull", "--rebase"])
+    """
+
+    def __init__(self, path: str):
+        """Initialize with repository path."""
+        self.path = path
+
+    def check_output(self, cmd: List[str], **kwargs) -> str:
+        """
+        Run git command and return output.
+
+        Args:
+            cmd: Git command arguments (without 'git' and '-C path')
+            **kwargs: Additional arguments for subprocess.check_output
+
+        Returns:
+            Command output as string (stripped)
+        """
+        kwargs.setdefault('text', True)
+        kwargs.setdefault('stderr', subprocess.DEVNULL)
+        result = subprocess.check_output(
+            ["git", "-C", self.path] + cmd,
+            **kwargs
+        )
+        return result.strip() if isinstance(result, str) else result
+
+    def run(self, cmd: List[str], check: bool = True, **kwargs) -> subprocess.CompletedProcess:
+        """
+        Run git command and return CompletedProcess.
+
+        Args:
+            cmd: Git command arguments (without 'git' and '-C path')
+            check: Raise on non-zero exit (default True)
+            **kwargs: Additional arguments for subprocess.run
+
+        Returns:
+            CompletedProcess instance
+        """
+        kwargs.setdefault('text', True)
+        return subprocess.run(
+            ["git", "-C", self.path] + cmd,
+            check=check,
+            **kwargs
+        )
+
+    def toplevel(self) -> Optional[str]:
+        """Get repository root path, resolved to canonical form."""
+        try:
+            out = self.check_output(["rev-parse", "--show-toplevel"])
+            return os.path.realpath(out)
+        except subprocess.CalledProcessError:
+            return None
+
+    def current_branch(self) -> Optional[str]:
+        """Get current branch name, or None if detached."""
+        try:
+            return self.check_output(["symbolic-ref", "--short", "HEAD"])
+        except subprocess.CalledProcessError:
+            return None
+
+    def current_head(self) -> Optional[str]:
+        """Get current HEAD commit SHA."""
+        try:
+            return self.check_output(["rev-parse", "HEAD"])
+        except subprocess.CalledProcessError:
+            return None
+
+    def is_clean(self) -> bool:
+        """Check if repo has no uncommitted changes to tracked files."""
+        try:
+            result = self.run(
+                ["status", "--porcelain", "-uno"],
+                check=False,
+                capture_output=True
+            )
+            return result.returncode == 0 and not result.stdout.strip()
+        except subprocess.CalledProcessError:
+            return False
+
+    def origin_url(self) -> Optional[str]:
+        """Get origin remote URL."""
+        try:
+            return self.check_output(["remote", "get-url", "origin"])
+        except subprocess.CalledProcessError:
+            return None
+
+    def config_get(self, key: str) -> Optional[str]:
+        """Get git config value."""
+        try:
+            return self.check_output(["config", "--get", key])
+        except subprocess.CalledProcessError:
+            return None
+
+    def config_set(self, key: str, value: str) -> bool:
+        """Set git config value. Returns True on success."""
+        try:
+            self.run(["config", key, value], capture_output=True)
+            return True
+        except subprocess.CalledProcessError:
+            return False
+
+    def rev_list_count(self, range_spec: str) -> int:
+        """Count commits in range."""
+        try:
+            out = self.check_output(["rev-list", "--count", range_spec])
+            return int(out)
+        except (subprocess.CalledProcessError, ValueError):
+            return 0
+
+    def log(self, args: List[str]) -> str:
+        """Run git log with given arguments."""
+        try:
+            return self.check_output(["log"] + args)
+        except subprocess.CalledProcessError:
+            return ""
+
+    def diff_stat(self, range_spec: str) -> str:
+        """Get diff --stat for range."""
+        try:
+            return self.check_output(["diff", "--stat", range_spec])
+        except subprocess.CalledProcessError:
+            return ""
+
+
+class FzfMenu:
+    """
+    Builder for fzf menus.
+
+    Usage:
+        menu = FzfMenu(header="Select an option", prompt="Choice: ")
+        menu.add_option("opt1", "Option One", "Description of option one")
+        menu.add_option("opt2", "Option Two", "Description of option two")
+        menu.add_bind("ctrl-a", "select-all")
+        selected = menu.show()
+    """
+
+    def __init__(
+        self,
+        header: str = "",
+        prompt: str = "> ",
+        multi: bool = False,
+        height: str = "~50%",
+        ansi: bool = True,
+        no_sort: bool = False,
+    ):
+        """
+        Initialize menu builder.
+
+        Args:
+            header: Header text shown above menu
+            prompt: Prompt text
+            multi: Allow multiple selections
+            height: fzf height (e.g., "~50%", "20")
+            ansi: Enable ANSI color codes
+            no_sort: Disable sorting (preserve order)
+        """
+        self.header = header
+        self.prompt = prompt
+        self.multi = multi
+        self.height = height
+        self.ansi = ansi
+        self.no_sort = no_sort
+        self.options: List[Tuple[str, str]] = []  # (value, display_line)
+        self.binds: List[Tuple[str, str]] = []  # (key, action)
+        self.extra_args: List[str] = []
+
+    def add_option(self, value: str, display: str = "", description: str = "") -> "FzfMenu":
+        """
+        Add menu option.
+
+        Args:
+            value: Value returned when selected (first field before tab)
+            display: Display text (if empty, uses value)
+            description: Optional description appended after display
+
+        Returns:
+            self for chaining
+        """
+        if display:
+            if description:
+                line = f"{value}\t{display}\t{description}"
+            else:
+                line = f"{value}\t{display}"
+        else:
+            line = value
+        self.options.append((value, line))
+        return self
+
+    def add_line(self, line: str) -> "FzfMenu":
+        """Add raw line to menu (for separators, headers, etc.)."""
+        self.options.append(("", line))
+        return self
+
+    def add_bind(self, key: str, action: str) -> "FzfMenu":
+        """Add key binding."""
+        self.binds.append((key, action))
+        return self
+
+    def add_arg(self, *args: str) -> "FzfMenu":
+        """Add extra fzf arguments."""
+        self.extra_args.extend(args)
+        return self
+
+    def show(self) -> Optional[Union[str, List[str]]]:
+        """
+        Show the menu and return selection.
+
+        Returns:
+            - Single string if multi=False
+            - List of strings if multi=True
+            - None if cancelled or fzf not available
+        """
+        if not fzf_available():
+            return None
+
+        cmd = ["fzf"]
+
+        if self.multi:
+            cmd.append("--multi")
+        else:
+            cmd.append("--no-multi")
+
+        if self.header:
+            cmd.extend(["--header", self.header])
+
+        if self.prompt:
+            cmd.extend(["--prompt", self.prompt])
+
+        if self.height:
+            cmd.extend(["--height", self.height])
+
+        if self.ansi:
+            cmd.append("--ansi")
+
+        if self.no_sort:
+            cmd.append("--no-sort")
+
+        # Use first field as selection value
+        cmd.extend(["--with-nth", "2.."])
+        cmd.extend(["--delimiter", "\t"])
+
+        for key, action in self.binds:
+            cmd.extend(["--bind", f"{key}:{action}"])
+
+        cmd.extend(self.extra_args)
+
+        # Add theme colors
+        cmd.extend(get_fzf_color_args())
+
+        menu_input = "\n".join(line for _, line in self.options)
+
+        try:
+            result = subprocess.run(
+                cmd,
+                input=menu_input,
+                capture_output=True,
+                text=True,
+            )
+        except FileNotFoundError:
+            return None
+
+        if result.returncode != 0:
+            return None
+
+        output = result.stdout.strip()
+        if not output:
+            return None
+
+        if self.multi:
+            # Return list of first fields (values)
+            selections = []
+            for line in output.split("\n"):
+                parts = line.split("\t")
+                selections.append(parts[0] if parts else line)
+            return selections
+        else:
+            # Return first field (value)
+            parts = output.split("\t")
+            return parts[0] if parts else output
+
+
+def fzf_available() -> bool:
+    """Check if fzf is available."""
+    return shutil.which("fzf") is not None
+
+
+def parse_help_options(script_path: str, cmd: str) -> List[Tuple[str, str]]:
+    """
+    Parse options from a command's --help output.
+
+    Args:
+        script_path: Path to the script executable
+        cmd: Command name (e.g., "status", "init clone")
+
+    Returns:
+        List of (option_flag, description) tuples.
+        e.g., [("--verbose", "Show verbose output"), ("-v", "Verbose")]
+    """
+    try:
+        # Build command: script_path cmd --help
+        cmd_parts = [script_path] + cmd.split() + ["--help"]
+        result = subprocess.run(
+            cmd_parts,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        help_text = result.stdout + result.stderr
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return []
+
+    options: List[Tuple[str, str]] = []
+    in_options_section = False
+    current_option = None
+    current_desc_lines: List[str] = []
+
+    for line in help_text.split("\n"):
+        # Detect start of options section
+        if line.strip().lower() in ("options:", "optional arguments:"):
+            in_options_section = True
+            continue
+
+        # Detect end of options section (new section or end)
+        if in_options_section and line and not line.startswith(" ") and not line.startswith("\t"):
+            # Save any pending option
+            if current_option and current_option not in ("-h", "--help", "-h, --help"):
+                desc = " ".join(current_desc_lines).strip()
+                # Remove default value info for cleaner display
+                if "(default:" in desc:
+                    desc = desc[:desc.rfind("(default:")].strip()
+                options.append((current_option, desc))
+            in_options_section = False
+            current_option = None
+            current_desc_lines = []
+            continue
+
+        if not in_options_section:
+            continue
+
+        # Parse option lines
+        stripped = line.strip()
+        if not stripped:
+            continue
+
+        # Check if this is a new option line (starts with -)
+        if stripped.startswith("-"):
+            # Save previous option if exists
+            if current_option and current_option not in ("-h", "--help", "-h, --help"):
+                desc = " ".join(current_desc_lines).strip()
+                if "(default:" in desc:
+                    desc = desc[:desc.rfind("(default:")].strip()
+                options.append((current_option, desc))
+
+            # Parse new option
+            # Format: "-v, --verbose  Description" or "--path PATH  Description"
+            parts = stripped.split()
+            opt_parts = []
+            desc_start = 0
+            for i, part in enumerate(parts):
+                if part.startswith("-"):
+                    opt_parts.append(part.rstrip(","))
+                elif part.isupper() and i > 0:
+                    # This is likely an argument placeholder like PATH
+                    continue
+                else:
+                    desc_start = i
+                    break
+
+            # Prefer long option if available
+            current_option = opt_parts[-1] if opt_parts else None
+            # For combined short/long like "-v, --verbose", show both
+            if len(opt_parts) > 1:
+                current_option = ", ".join(opt_parts)
+
+            current_desc_lines = [" ".join(parts[desc_start:])] if desc_start > 0 else []
+        else:
+            # Continuation of description
+            current_desc_lines.append(stripped)
+
+    # Don't forget the last option
+    if current_option and current_option not in ("-h", "--help", "-h, --help"):
+        desc = " ".join(current_desc_lines).strip()
+        if "(default:" in desc:
+            desc = desc[:desc.rfind("(default:")].strip()
+        options.append((current_option, desc))
+
+    return options
+
+
+def fzf_expandable_menu(
+    commands: List[Tuple[str, str, List[Tuple[str, str]]]],
+    header: str = "Enter=select | \\=expand/collapse | q=quit",
+    prompt: str = "> ",
+    height: str = "~80%",
+    preview_cmd: Optional[str] = None,
+    preview_window: str = "right,60%,wrap",
+    options_provider: Optional[Callable[[str], List[Tuple[str, str]]]] = None,
+    categories: Optional[Dict[str, str]] = None,
+    sort_key: Optional[str] = None,
+    initial_selection: Optional[str] = None,
+) -> Optional[Union[str, Tuple[str, str]]]:
+    """
+    Show an fzf menu with expandable subcommands.
+
+    Args:
+        commands: List of (cmd, description, [(subcmd, subdesc), ...]) tuples.
+                  Commands should be in display order (alphabetical).
+        header: Header text shown in fzf
+        prompt: Prompt text
+        height: fzf height setting
+        preview_cmd: Optional shell command for preview pane ({1} = selected value)
+        preview_window: Preview window position/size if preview_cmd is set
+        options_provider: Optional function that takes a command name and returns
+                          a list of (option, description) tuples for that command.
+                          Used for verbose mode (v key) to show command options.
+        categories: Optional dict mapping command names to category header strings.
+                    If a command has a category, a separator header is shown before it.
+                    Example: {"explore": "Git/Repository", "config": "Configuration"}
+        sort_key: Optional key binding that triggers sort mode cycling.
+                  When pressed, returns ("SORT", current_selection) tuple.
+        initial_selection: Optional command name to position cursor on initially.
+
+    Returns:
+        - Selected command string on Enter
+        - ("SORT", current_selection) tuple when sort_key is pressed
+        - None if cancelled
+    """
+    if not fzf_available():
+        return None
+
+    expanded_cmds: Set[str] = set()
+    expanded_opts: Set[str] = set()  # Commands with options expanded
+    options_cache: Dict[str, List[Tuple[str, str]]] = {}  # Cache parsed options
+    current_selection: Optional[str] = initial_selection
+    preview_hidden: bool = False
+
+    while True:
+        # Build menu lines
+        menu_lines: List[str] = []
+
+        # Calculate max length including subcommands and options
+        all_cmds = []
+        for cmd, desc, subs in commands:
+            all_cmds.append(cmd)
+            if cmd in expanded_cmds or cmd in expanded_opts:
+                for subcmd, _ in subs:
+                    all_cmds.append(subcmd)
+            if cmd in expanded_opts and options_provider:
+                if cmd not in options_cache:
+                    options_cache[cmd] = options_provider(cmd)
+                for opt, _ in options_cache.get(cmd, []):
+                    all_cmds.append(opt)
+                # Also include subcommand options in length calculation
+                for subcmd, _ in subs:
+                    if subcmd not in options_cache:
+                        options_cache[subcmd] = options_provider(subcmd)
+                    for opt, _ in options_cache.get(subcmd, []):
+                        all_cmds.append(opt)
+        max_cmd_len = max(len(c) for c in all_cmds) if all_cmds else 12
+
+        for cmd, desc, subs in commands:
+            # Check if this command starts a new category
+            if categories and cmd in categories:
+                cat_label = categories[cmd]
+                # Add category separator (non-selectable via SEPARATOR key)
+                separator_line = f"SEPARATOR\t\033[1;34m── {cat_label} ──\033[0m"
+                menu_lines.append(separator_line)
+            has_subs = len(subs) > 0
+            is_expanded = cmd in expanded_cmds
+            has_opts_expanded = cmd in expanded_opts
+
+            # Prefix: + for expandable, - for expanded, space otherwise
+            if has_subs:
+                prefix = "- " if (is_expanded or has_opts_expanded) else "+ "
+            else:
+                prefix = "  "
+
+            colored_cmd = f"\033[36m{cmd:<{max_cmd_len}}\033[0m"
+            menu_lines.append(f"{cmd}\t{prefix}{colored_cmd}  {desc}")
+
+            # Build tree structure for sub-items
+            # Level 1: parent's options + subcommands (direct children)
+            # Level 2: subcommand's options (children of subcommands)
+
+            level1_items: List[Tuple[str, str, List[Tuple[str, str]]]] = []
+            # (key, display, children) where children are level2 items
+
+            # Add parent's options first (if v was pressed) - no children
+            if has_opts_expanded and options_provider:
+                if cmd not in options_cache:
+                    options_cache[cmd] = options_provider(cmd)
+                for opt, optdesc in options_cache.get(cmd, []):
+                    colored_opt = f"\033[33m{opt:<{max_cmd_len}}\033[0m"  # Yellow
+                    level1_items.append((opt, f"{colored_opt}  {optdesc}", []))
+
+            # Add subcommands (if \ or v was pressed)
+            if is_expanded or has_opts_expanded:
+                for subcmd, subdesc in subs:
+                    colored_subcmd = f"\033[36m{subcmd:<{max_cmd_len}}\033[0m"
+                    children: List[Tuple[str, str]] = []
+
+                    # If verbose mode, collect subcommand's options as children
+                    if has_opts_expanded and options_provider:
+                        if subcmd not in options_cache:
+                            options_cache[subcmd] = options_provider(subcmd)
+                        for opt, optdesc in options_cache.get(subcmd, []):
+                            colored_opt = f"\033[33m{opt:<{max_cmd_len}}\033[0m"
+                            children.append((opt, f"{colored_opt}  {optdesc}"))
+
+                    level1_items.append((subcmd, f"{colored_subcmd}  {subdesc}", children))
+
+            # Render tree with proper connectors
+            for i, (key, display, children) in enumerate(level1_items):
+                is_last_l1 = (i == len(level1_items) - 1)
+                tree_char = "└─" if is_last_l1 else "├─"
+                menu_lines.append(f"{key}\t  {tree_char} {display}")
+
+                # Render children (level 2)
+                for j, (child_key, child_display) in enumerate(children):
+                    is_last_l2 = (j == len(children) - 1)
+                    # Continuation line: │ if parent wasn't last, space if it was
+                    continuation = "   " if is_last_l1 else "│  "
+                    child_tree = "└─" if is_last_l2 else "├─"
+                    menu_lines.append(f"{child_key}\t  {continuation} {child_tree} {child_display}")
+
+        menu_input = "\n".join(menu_lines)
+
+        # Build fzf command
+        fzf_args = [
+            "fzf",
+            "--no-multi",
+            "--no-sort",
+            "--no-info",
+            "--ansi",
+            "--sync",  # Ensure input is fully loaded before start event fires
+            "--layout=reverse-list",
+            "--height", height,
+            "--header", header,
+            "--prompt", prompt,
+            "--with-nth", "2..",
+            "--delimiter", "\t",
+            "--bind", "q:abort",
+        ]
+
+        # Apply theme colors
+        theme_colors = get_fzf_theme()
+        if theme_colors:
+            fzf_args.extend(["--color", theme_colors])
+
+        # Build expected keys list
+        expect_keys = ["\\"]  # backslash for subcommand expand/collapse
+        if options_provider:
+            expect_keys.append("v")  # v for options expand/collapse
+        if preview_cmd:
+            expect_keys.append("?")  # ? for preview toggle
+        if sort_key:
+            expect_keys.append(sort_key)  # for sort mode cycling
+
+        # Add preview if specified
+        if preview_cmd:
+            window = f"{preview_window},hidden" if preview_hidden else preview_window
+            fzf_args.extend([
+                "--preview", preview_cmd,
+                "--preview-window", window,
+                "--bind", "ctrl-d:preview-half-page-down",
+                "--bind", "ctrl-u:preview-half-page-up",
+                "--bind", "page-down:preview-page-down",
+                "--bind", "page-up:preview-page-up",
+            ])
+            fzf_args.extend(get_fzf_preview_resize_bindings())
+
+        fzf_args.extend(["--expect", ",".join(expect_keys)])
+
+        # Position cursor on previously selected item after expand/collapse
+        if current_selection:
+            for i, line in enumerate(menu_lines):
+                if line.startswith(current_selection + '\t'):
+                    fzf_args.extend(["--bind", f"start:pos({i + 1})"])
+                    break
+
+        try:
+            result = subprocess.run(
+                fzf_args,
+                input=menu_input,
+                stdout=subprocess.PIPE,
+                text=True,
+            )
+        except FileNotFoundError:
+            return None
+
+        if result.returncode != 0 or not result.stdout.strip():
+            return None
+
+        # Don't strip() before split - first line is empty when Enter pressed
+        lines = result.stdout.split("\n")
+        key_pressed = lines[0] if lines else ""
+        selection = lines[1].strip() if len(lines) > 1 else ""
+
+        if not selection:
+            return None
+
+        selected_cmd = selection.split("\t")[0]
+
+        # Handle sort mode cycling first (works on any line including separators)
+        if sort_key and key_pressed == sort_key:
+            # Return special tuple to signal sort mode change request
+            # Use a valid command for cursor positioning, not SEPARATOR
+            cursor_cmd = selected_cmd if selected_cmd != "SEPARATOR" else None
+            return ("SORT", cursor_cmd)
+
+        # Handle preview toggle with ? (works on any line)
+        if preview_cmd and key_pressed == "?":
+            preview_hidden = not preview_hidden
+            if selected_cmd != "SEPARATOR":
+                current_selection = selected_cmd
+            continue
+
+        # Skip category separator lines - they're not selectable for other actions
+        if selected_cmd == "SEPARATOR":
+            continue
+
+        # Handle expand/collapse subcommands with backslash
+        if key_pressed == "\\":
+            for cmd, _, subs in commands:
+                if cmd == selected_cmd and subs:
+                    if cmd in expanded_cmds:
+                        expanded_cmds.discard(cmd)
+                    else:
+                        expanded_cmds.add(cmd)
+                    current_selection = cmd
+                    break
+            continue
+
+        # Handle expand/collapse options with v (verbose)
+        if key_pressed == "v" and options_provider:
+            # Only allow options on top-level commands
+            for cmd, _, _ in commands:
+                if cmd == selected_cmd:
+                    if cmd in expanded_opts:
+                        expanded_opts.discard(cmd)
+                    else:
+                        expanded_opts.add(cmd)
+                    current_selection = cmd
+                    break
+            continue
+
+        # Regular Enter - return the selected command
+        return selected_cmd
+
+
+# =============================================================================
+# State Management
+# =============================================================================
+
+def load_defaults(defaults_file: str) -> dict:
+    """Load defaults from JSON file."""
+    if not os.path.exists(defaults_file):
+        return {}
+    try:
+        with open(defaults_file, encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            # Convert repo defaults to strings, but preserve special keys
+            result = {}
+            for k, v in data.items():
+                if k in ("__extra_repos__", "__hidden_repos__"):
+                    result[k] = v if isinstance(v, list) else []
+                elif k == "__push_targets__":
+                    result[k] = v if isinstance(v, dict) else {}
+                else:
+                    result[str(k)] = str(v)
+            return result
+    except Exception:
+        pass
+    return {}
+
+
+def save_defaults(defaults_file: str, defaults: dict) -> None:
+    """Save defaults to JSON file."""
+    with open(defaults_file, "w", encoding="utf-8") as f:
+        json.dump(defaults, f, indent=2, sort_keys=True)
+
+
+def load_prep_state(path: str) -> Optional[Dict]:
+    """Load prep state from JSON file. Returns None if not found."""
+    if not os.path.exists(path):
+        return None
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict) and "repos" in data:
+            return data
+    except Exception:
+        pass
+    return None
+
+
+def save_prep_state(path: str, repos_data: Dict) -> None:
+    """Save prep state to JSON file."""
+    state = {
+        "timestamp": datetime.now().isoformat(),
+        "repos": repos_data
+    }
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(state, f, indent=2)
+
+
+def load_export_state(path: str) -> Dict[str, Dict[str, str]]:
+    """Load export state from JSON file."""
+    if not os.path.exists(path):
+        return {}
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            return data
+    except Exception:
+        pass
+    return {}
+
+
+def save_export_state(path: str, state: Dict[str, Dict[str, str]]) -> None:
+    """Save export state to JSON file."""
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(state, f, indent=2, sort_keys=True)
+
+
+# =============================================================================
+# Standalone helper functions (for backward compatibility)
+# =============================================================================
+
+def git_toplevel(path: str) -> Optional[str]:
+    """Get the git repository root for a path, resolved to canonical form."""
+    return GitRepo(path).toplevel()
+
+
+def current_branch(repo: str) -> Optional[str]:
+    """Get current branch name for repo."""
+    return GitRepo(repo).current_branch()
+
+
+def current_head(repo: str) -> Optional[str]:
+    """Get current HEAD commit SHA for repo."""
+    return GitRepo(repo).current_head()
+
+
+def repo_is_clean(repo: str) -> bool:
+    """Check if repo has no uncommitted changes to tracked files."""
+    return GitRepo(repo).is_clean()