bitp 1.0.6__py3-none-any.whl

bitbake_project/commands/fragment.py

@@ -0,0 +1,884 @@
+#
+# Copyright (C) 2025 Bruce Ashfield <bruce.ashfield@gmail.com>
+#
+# SPDX-License-Identifier: GPL-2.0-only
+#
+"""Fragment command - browse and manage OE configuration fragments."""
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Tuple
+
+from ..core import Colors, fzf_available, get_fzf_color_args, get_fzf_preview_resize_bindings, terminal_color
+from .common import resolve_bblayers_path, extract_layer_paths
+from .projects import get_preview_window_arg
+
+
+# =============================================================================
+# Data Classes
+# =============================================================================
+
+@dataclass
+class Fragment:
+    """Represents a configuration fragment."""
+    name: str           # e.g., "meta/yocto/root-login-with-empty-password"
+    path: str           # Full filesystem path to .conf file (empty for builtin)
+    layer: str          # Layer name (e.g., "meta")
+    domain: str         # Domain path (e.g., "yocto")
+    summary: str        # BB_CONF_FRAGMENT_SUMMARY value
+    description: str    # BB_CONF_FRAGMENT_DESCRIPTION value
+    is_enabled: bool    # Whether in OE_FRAGMENTS
+    is_builtin: bool    # Whether this is a built-in fragment (machine/distro)
+
+
+@dataclass
+class BuiltinPrefix:
+    """Represents a built-in fragment prefix (machine:MACHINE, distro:DISTRO)."""
+    prefix: str         # e.g., "machine"
+    variable: str       # e.g., "MACHINE"
+
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+# Default built-in fragment prefixes from OE-core bitbake.conf
+DEFAULT_BUILTIN_PREFIXES = [
+    BuiltinPrefix("machine", "MACHINE"),
+    BuiltinPrefix("distro", "DISTRO"),
+]
+
+
+# =============================================================================
+# toolcfg.conf Parsing
+# =============================================================================
+
+def _get_toolcfg_path(bblayers_path: Optional[str] = None) -> str:
+    """
+    Find toolcfg.conf relative to build directory.
+
+    Returns path to conf/toolcfg.conf relative to the build directory
+    containing bblayers.conf.
+    """
+    if bblayers_path:
+        # toolcfg.conf is in the same conf/ directory as bblayers.conf
+        conf_dir = os.path.dirname(bblayers_path)
+        return os.path.join(conf_dir, "toolcfg.conf")
+
+    # Default locations
+    candidates = ["conf/toolcfg.conf", "build/conf/toolcfg.conf"]
+    for cand in candidates:
+        parent_conf = os.path.dirname(cand)
+        if os.path.isdir(parent_conf):
+            return cand
+
+    return "conf/toolcfg.conf"
+
+
+def _parse_enabled_fragments(toolcfg_path: str) -> List[str]:
+    """
+    Parse OE_FRAGMENTS from toolcfg.conf using regex.
+
+    Handles:
+    - OE_FRAGMENTS = "..."
+    - OE_FRAGMENTS += "..."
+    - Line continuations with backslash
+    """
+    if not os.path.isfile(toolcfg_path):
+        return []
+
+    try:
+        with open(toolcfg_path, "r") as f:
+            content = f.read()
+    except (OSError, IOError):
+        return []
+
+    # Handle line continuations
+    content = content.replace("\\\n", " ")
+
+    # Match OE_FRAGMENTS = "..." or OE_FRAGMENTS += "..."
+    # Collect all values (multiple assignments get concatenated)
+    fragments = []
+    pattern = re.compile(r'OE_FRAGMENTS\s*\+?=\s*"([^"]*)"', re.MULTILINE)
+
+    for match in pattern.finditer(content):
+        value = match.group(1).strip()
+        if value:
+            fragments.extend(value.split())
+
+    return fragments
+
+
+def _ensure_toolcfg_exists(toolcfg_path: str) -> None:
+    """Create toolcfg.conf with default content if it doesn't exist."""
+    if os.path.exists(toolcfg_path):
+        return
+
+    # Create conf directory if needed
+    conf_dir = os.path.dirname(toolcfg_path)
+    if conf_dir and not os.path.isdir(conf_dir):
+        os.makedirs(conf_dir, exist_ok=True)
+
+    with open(toolcfg_path, "w") as f:
+        f.write("""# Automated config file controlled by bit/bitbake-config-build
+#
+# Run 'bit fragment enable <fragment-name>' to enable additional fragments
+# or replace built-in ones (e.g. machine/<name> or distro/<name> to change MACHINE or DISTRO).
+
+OE_FRAGMENTS += ""
+""")
+
+
+def _update_oe_fragments(
+    toolcfg_path: str,
+    to_add: List[str],
+    to_remove: List[str],
+    builtin_prefixes: List[BuiltinPrefix],
+) -> bool:
+    """
+    Update OE_FRAGMENTS variable in toolcfg.conf.
+
+    - Adds new fragments
+    - Removes specified fragments
+    - For builtin fragments (machine/, distro/), removes existing value with same prefix
+
+    Returns True if file was modified.
+    """
+    _ensure_toolcfg_exists(toolcfg_path)
+
+    with open(toolcfg_path, "r") as f:
+        content = f.read()
+
+    # Parse current fragments
+    current = _parse_enabled_fragments(toolcfg_path)
+
+    # Get builtin prefix names for special handling
+    builtin_prefix_names = {p.prefix for p in builtin_prefixes}
+
+    # Process removals
+    for fragment in to_remove:
+        if fragment in current:
+            current.remove(fragment)
+        # Also handle prefix-based removal (e.g., "machine/" removes all machine/*)
+        if fragment.endswith("/"):
+            current = [f for f in current if not f.startswith(fragment)]
+
+    # Process additions
+    for fragment in to_add:
+        if fragment in current:
+            continue
+
+        # For builtin fragments, remove existing with same prefix first
+        prefix = fragment.split("/", 1)[0]
+        if prefix in builtin_prefix_names:
+            current = [f for f in current if not f.startswith(f"{prefix}/")]
+
+        current.append(fragment)
+
+    # Update the file
+    new_value = " ".join(current)
+
+    # Check if OE_FRAGMENTS line exists
+    pattern = re.compile(r'(OE_FRAGMENTS\s*\+?=\s*)"[^"]*"', re.MULTILINE)
+
+    if pattern.search(content):
+        # Replace existing line
+        new_content = pattern.sub(rf'\1"{new_value}"', content, count=1)
+    else:
+        # Add new line
+        new_content = content.rstrip() + f'\n\nOE_FRAGMENTS += "{new_value}"\n'
+
+    if new_content == content:
+        return False
+
+    with open(toolcfg_path, "w") as f:
+        f.write(new_content)
+
+    return True
+
+
+# =============================================================================
+# Fragment Discovery
+# =============================================================================
+
+def _parse_fragment_metadata(conf_path: str) -> Tuple[str, str]:
+    """
+    Extract BB_CONF_FRAGMENT_SUMMARY and BB_CONF_FRAGMENT_DESCRIPTION from a .conf file.
+
+    Returns (summary, description).
+    """
+    summary = ""
+    description = ""
+
+    try:
+        with open(conf_path, "r", encoding="utf-8", errors="ignore") as f:
+            content = f.read()
+    except (OSError, IOError):
+        return summary, description
+
+    # Parse BB_CONF_FRAGMENT_SUMMARY = "..."
+    summary_match = re.search(r'BB_CONF_FRAGMENT_SUMMARY\s*=\s*"([^"]*)"', content)
+    if summary_match:
+        summary = summary_match.group(1).strip()
+
+    # Parse BB_CONF_FRAGMENT_DESCRIPTION = "..."
+    # This can be multiline with backslash continuation
+    desc_match = re.search(r'BB_CONF_FRAGMENT_DESCRIPTION\s*=\s*"([^"]*(?:\\\n[^"]*)*)"', content)
+    if desc_match:
+        description = desc_match.group(1).strip()
+        # Clean up line continuations
+        description = description.replace("\\\n", " ").replace("  ", " ")
+
+    return summary, description
+
+
+def _get_layer_name(layer_path: str) -> str:
+    """
+    Get layer name from layer.conf BBFILE_COLLECTIONS.
+    Falls back to directory name.
+    """
+    layer_conf = os.path.join(layer_path, "conf", "layer.conf")
+
+    if os.path.isfile(layer_conf):
+        try:
+            with open(layer_conf, "r") as f:
+                content = f.read()
+            match = re.search(r'BBFILE_COLLECTIONS\s*\+?=\s*"([^"]*)"', content)
+            if match:
+                # Take first collection name
+                names = match.group(1).strip().split()
+                if names:
+                    return names[0]
+        except (OSError, IOError):
+            pass
+
+    return os.path.basename(layer_path)
+
+
+def _discover_fragments(layer_paths: List[str], progress: bool = True) -> List[Fragment]:
+    """
+    Scan layers for fragments in conf/fragments/<domain>/*.conf.
+
+    Returns list of Fragment objects.
+    """
+    fragments = []
+
+    if progress:
+        print(Colors.dim("Scanning fragments..."), end=" ", flush=True)
+
+    for layer_path in layer_paths:
+        layer_name = _get_layer_name(layer_path)
+        fragments_dir = os.path.join(layer_path, "conf", "fragments")
+
+        if not os.path.isdir(fragments_dir):
+            continue
+
+        for root, dirs, files in os.walk(fragments_dir):
+            # Get domain relative to fragments_dir
+            domain = os.path.relpath(root, fragments_dir)
+            if domain == ".":
+                domain = ""
+
+            for conf_file in sorted(files):
+                if not conf_file.endswith(".conf") or conf_file.startswith("."):
+                    continue
+
+                conf_path = os.path.join(root, conf_file)
+                name_base = conf_file[:-5]  # Remove .conf
+
+                # Build fragment name: layer/domain/name
+                if domain:
+                    fragment_name = f"{layer_name}/{domain}/{name_base}"
+                else:
+                    fragment_name = f"{layer_name}/{name_base}"
+
+                # Normalize path separators
+                fragment_name = fragment_name.replace("\\", "/")
+
+                summary, description = _parse_fragment_metadata(conf_path)
+
+                fragments.append(Fragment(
+                    name=fragment_name,
+                    path=conf_path,
+                    layer=layer_name,
+                    domain=domain,
+                    summary=summary or "(no summary)",
+                    description=description or "",
+                    is_enabled=False,
+                    is_builtin=False,
+                ))
+
+    if progress:
+        print(Colors.dim(f"{len(fragments)} fragments found"))
+
+    return fragments
+
+
+def _get_enabled_builtin_values(
+    enabled_fragments: List[str],
+    prefixes: List[BuiltinPrefix],
+) -> Dict[str, str]:
+    """
+    Extract current values for builtin fragments.
+
+    E.g., if OE_FRAGMENTS contains "machine/qemuarm64", return {"machine": "qemuarm64"}
+    """
+    result = {}
+    prefix_names = {p.prefix for p in prefixes}
+
+    for fragment in enabled_fragments:
+        if "/" in fragment:
+            prefix, value = fragment.split("/", 1)
+            if prefix in prefix_names:
+                result[prefix] = value
+
+    return result
+
+
+# =============================================================================
+# FZF Browser
+# =============================================================================
+
+def _build_fragment_menu(
+    fragments: List[Fragment],
+    builtin_prefixes: List[BuiltinPrefix],
+    enabled_builtins: Dict[str, str],
+    toolcfg_path: str = "",
+) -> str:
+    """Build fzf menu input with fragments grouped by layer/domain."""
+    lines = []
+
+    # Calculate column widths
+    max_name_len = max(len(f.name) for f in fragments) if fragments else 30
+    max_name_len = min(max_name_len, 50)
+
+    # Add config file entry at the top
+    if toolcfg_path:
+        config_name = "⚙ toolcfg.conf"
+        config_exists = os.path.isfile(toolcfg_path)
+        status = Colors.cyan("[config]") if config_exists else Colors.dim("[config]")
+        summary = toolcfg_path if config_exists else "(will be created)"
+        lines.append(f"__CONFIG__\t{Colors.cyan(f'{config_name:<{max_name_len}}')}  {status}  {summary}")
+        lines.append(f"---\t{Colors.dim('── Fragments ──')}")
+
+    # Show enabled fragments first
+    enabled = [f for f in fragments if f.is_enabled]
+    disabled = [f for f in fragments if not f.is_enabled]
+
+    # Add builtin prefixes as special entries
+    for prefix in builtin_prefixes:
+        current_value = enabled_builtins.get(prefix.prefix, "")
+        if current_value:
+            name = f"{prefix.prefix}/{current_value}"
+            status = terminal_color("fragment_enabled", "[enabled]")
+            summary = f"Sets {prefix.variable} = {current_value}"
+            colored_name = terminal_color("fragment_enabled", f"{name:<{max_name_len}}")
+            line = f"{name}\t{colored_name}  {status}  {summary}"
+        else:
+            name = f"{prefix.prefix}/..."
+            status = Colors.dim("[builtin]")
+            summary = f"Sets {prefix.variable} = <value>"
+            line = f"{name}\t{Colors.dim(f'{name:<{max_name_len}}')}  {status}  {summary}"
+        lines.append(line)
+
+    if builtin_prefixes:
+        lines.append(f"---\t{Colors.dim('── File Fragments ──')}")
+
+    # Enabled fragments
+    if enabled:
+        for f in enabled:
+            status = terminal_color("fragment_enabled", "[enabled]")
+            colored_name = terminal_color("fragment_enabled", f"{f.name:<{max_name_len}}")
+            line = f"{f.name}\t{colored_name}  {status}  {f.summary[:50]}"
+            lines.append(line)
+
+    # Disabled fragments
+    if disabled:
+        if enabled:
+            lines.append(f"---\t{Colors.dim('── Available ──')}")
+        for f in disabled:
+            status = Colors.dim("[      ]")
+            line = f"{f.name}\t{f.name:<{max_name_len}}  {status}  {f.summary[:50]}"
+            lines.append(line)
+
+    return "\n".join(lines)
+
+
+def _fragment_fzf_browser(
+    fragments: List[Fragment],
+    builtin_prefixes: List[BuiltinPrefix],
+    enabled_builtins: Dict[str, str],
+    toolcfg_path: str,
+) -> int:
+    """
+    Interactive fzf browser for fragments.
+
+    Key bindings:
+    - Enter: Toggle enable/disable
+    - Tab: Multi-select fragments
+    - e: Enable all selected
+    - d: Disable all selected
+    - v: View fragment file content
+    - c: View/edit toolcfg.conf
+    - ?: Toggle preview
+    - q: Quit
+    """
+    if not fragments and not builtin_prefixes:
+        print("No fragments found.")
+        return 1
+
+    if not fzf_available():
+        # Fall back to text list
+        _list_fragments_text(fragments, builtin_prefixes, enabled_builtins, verbose=False)
+        return 0
+
+    # Build preview script
+    preview_data = {f.name: {
+        "name": f.name,
+        "path": f.path,
+        "layer": f.layer,
+        "domain": f.domain,
+        "summary": f.summary,
+        "description": f.description,
+        "is_enabled": f.is_enabled,
+        "is_builtin": f.is_builtin,
+    } for f in fragments}
+
+    # Add builtin info
+    for prefix in builtin_prefixes:
+        value = enabled_builtins.get(prefix.prefix, "")
+        if value:
+            key = f"{prefix.prefix}/{value}"
+            preview_data[key] = {
+                "name": key,
+                "path": "",
+                "layer": "",
+                "domain": "",
+                "summary": f"Sets {prefix.variable} = {value}",
+                "description": f"Built-in fragment that sets the {prefix.variable} variable.",
+                "is_enabled": True,
+                "is_builtin": True,
+            }
+        # Also add the generic entry
+        key = f"{prefix.prefix}/..."
+        preview_data[key] = {
+            "name": key,
+            "path": "",
+            "layer": "",
+            "domain": "",
+            "summary": f"Sets {prefix.variable} = <value>",
+            "description": f"Built-in fragment. Use '{prefix.prefix}/<value>' to set {prefix.variable}.",
+            "is_enabled": False,
+            "is_builtin": True,
+        }
+
+    # Add config file entry
+    preview_data["__CONFIG__"] = {
+        "name": "toolcfg.conf",
+        "path": toolcfg_path,
+        "layer": "",
+        "domain": "",
+        "summary": "OE configuration file for fragments",
+        "description": "This file stores your enabled fragments (OE_FRAGMENTS variable).",
+        "is_enabled": False,
+        "is_builtin": False,
+        "is_config": True,
+    }
+
+    preview_data_file = tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False)
+    json.dump(preview_data, preview_data_file)
+    preview_data_file.close()
+
+    # Create preview script
+    preview_script = tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False)
+    preview_script.write(f'''#!/usr/bin/env python3
+import json
+import sys
+import os
+
+key = sys.argv[1] if len(sys.argv) > 1 else ""
+key = key.strip("'\\"")
+
+with open("{preview_data_file.name}", "r") as f:
+    data = json.load(f)
+
+frag = data.get(key, {{}})
+if not frag:
+    print(f"No data for: {{key}}")
+    sys.exit(0)
+
+# Special handling for config file entry
+if frag.get('is_config'):
+    path = frag.get('path', '')
+    print("\\033[1mtoolcfg.conf\\033[0m")
+    print(f"Path: {{path}}")
+    print()
+    if path and os.path.isfile(path):
+        print("\\033[36mContent:\\033[0m")
+        print("-" * 40)
+        with open(path, 'r') as f:
+            print(f.read())
+    else:
+        print("\\033[33mFile does not exist yet.\\033[0m")
+        print("It will be created when you enable a fragment.")
+    sys.exit(0)
+
+print(f"\\033[1m{{frag.get('name', '')}}\\033[0m")
+if frag.get('is_enabled'):
+    print("\\033[32mStatus: Enabled\\033[0m")
+else:
+    print("Status: Disabled")
+print()
+
+if frag.get('path'):
+    print(f"Path: {{frag['path']}}")
+    print(f"Layer: {{frag.get('layer', '')}}")
+    if frag.get('domain'):
+        print(f"Domain: {{frag['domain']}}")
+    print()
+
+print("\\033[36mSummary:\\033[0m")
+print(f"  {{frag.get('summary', '')}}")
+print()
+
+if frag.get('description'):
+    print("\\033[36mDescription:\\033[0m")
+    for line in frag['description'].split('\\n'):
+        print(f"  {{line}}")
+    print()
+
+# Show file content for non-builtin fragments
+if frag.get('path') and os.path.isfile(frag['path']):
+    print("\\033[36mContent:\\033[0m")
+    print("-" * 40)
+    with open(frag['path'], 'r') as f:
+        print(f.read())
+''')
+    preview_script.close()
+
+    preview_cmd = f'python3 "{preview_script.name}" {{1}}'
+
+    # Header (two lines)
+    header = "Enter=toggle | Tab=select | +/e=enable | -/d=disable\nv=view | c=edit conf | ?=preview | q=quit"
+
+    preview_window = get_preview_window_arg("50%")
+
+    fzf_args = [
+        "fzf",
+        "--multi",
+        "--ansi",
+        "--height", "100%",
+        "--layout=reverse-list",
+        "--header", header,
+        "--prompt", "Fragment: ",
+        "--with-nth", "2..",
+        "--delimiter", "\t",
+        "--preview", preview_cmd,
+        "--preview-window", preview_window,
+        "--bind", "?:toggle-preview",
+        "--bind", "pgup:preview-page-up",
+        "--bind", "pgdn:preview-page-down",
+        "--bind", "esc:abort",
+        "--expect", "e,d,v,c,q,+,-",
+    ]
+
+    fzf_args.extend(get_fzf_preview_resize_bindings())
+    fzf_args.extend(get_fzf_color_args())
+
+    next_selection = None  # Track item to select after enable/disable
+
+    try:
+        while True:
+            # Rebuild menu with current state
+            menu_input = _build_fragment_menu(fragments, builtin_prefixes, enabled_builtins, toolcfg_path)
+
+            # Build position binding if we have a selection to restore
+            run_args = fzf_args.copy()
+            if next_selection:
+                lines = menu_input.split('\n')
+                for i, line in enumerate(lines):
+                    if line.startswith(next_selection + '\t'):
+                        run_args.extend(["--bind", f"load:pos({i + 1})"])
+                        break
+                next_selection = None
+
+            result = subprocess.run(
+                run_args,
+                input=menu_input,
+                stdout=subprocess.PIPE,
+                text=True,
+            )
+
+            if result.returncode != 0 or not result.stdout.strip():
+                break
+
+            # Parse output
+            lines = result.stdout.strip().split("\n")
+            key = lines[0].strip() if lines else ""
+            selected = [l.split("\t")[0].strip() for l in lines[1:] if l.strip() and not l.startswith("---")]
+
+            if key == "q" or not selected:
+                break
+
+            if key == "v":
+                # View fragment content
+                for name in selected:
+                    frag = next((f for f in fragments if f.name == name), None)
+                    if frag and frag.path and os.path.isfile(frag.path):
+                        pager = os.environ.get("PAGER", "less")
+                        subprocess.run([pager, frag.path])
+                continue
+
+            if key == "c":
+                # View/edit toolcfg.conf
+                if os.path.isfile(toolcfg_path):
+                    editor = os.environ.get("EDITOR", os.environ.get("PAGER", "less"))
+                    subprocess.run([editor, toolcfg_path])
+                    # Refresh state after potential edits
+                    enabled_list = _parse_enabled_fragments(toolcfg_path)
+                    for f in fragments:
+                        f.is_enabled = f.name in enabled_list
+                    enabled_builtins.clear()
+                    enabled_builtins.update(_get_enabled_builtin_values(enabled_list, builtin_prefixes))
+                else:
+                    print(f"No toolcfg.conf yet (will be created when you enable a fragment)")
+                    input("Press Enter to continue...")
+                continue
+
+            # Handle enable/disable
+            to_enable = []
+            to_disable = []
+
+            for name in selected:
+                # Skip separator lines and config entry
+                if name == "---" or name.startswith("──") or name == "__CONFIG__":
+                    continue
+
+                # Check if this is a builtin prompt (e.g., "machine/...")
+                if name.endswith("/..."):
+                    prefix = name[:-4]
+                    # Prompt for value
+                    try:
+                        value = input(f"Enter value for {prefix}/: ").strip()
+                        if value:
+                            to_enable.append(f"{prefix}/{value}")
+                    except (EOFError, KeyboardInterrupt):
+                        print()
+                    continue
+
+                frag = next((f for f in fragments if f.name == name), None)
+                is_enabled = frag.is_enabled if frag else name in enabled_builtins.values()
+
+                if key in ("e", "+") or (key == "" and not is_enabled):
+                    to_enable.append(name)
+                elif key in ("d", "-") or (key == "" and is_enabled):
+                    to_disable.append(name)
+
+            # Update toolcfg.conf
+            if to_enable or to_disable:
+                modified = _update_oe_fragments(toolcfg_path, to_enable, to_disable, builtin_prefixes)
+                if modified:
+                    # Refresh state
+                    enabled_list = _parse_enabled_fragments(toolcfg_path)
+                    for f in fragments:
+                        f.is_enabled = f.name in enabled_list
+                    enabled_builtins = _get_enabled_builtin_values(enabled_list, builtin_prefixes)
+
+                # Preserve selection on the first modified item
+                if selected:
+                    next_selection = selected[0]
+
+    finally:
+        # Clean up temp files
+        for f in [preview_data_file.name, preview_script.name]:
+            try:
+                os.unlink(f)
+            except OSError:
+                pass
+
+    return 0
+
+
+# =============================================================================
+# Text Output
+# =============================================================================
+
+def _list_fragments_text(
+    fragments: List[Fragment],
+    builtin_prefixes: List[BuiltinPrefix],
+    enabled_builtins: Dict[str, str],
+    verbose: bool = False,
+) -> None:
+    """Print fragments as text output."""
+    # Print builtin info
+    print("Built-in fragments:")
+    for prefix in builtin_prefixes:
+        value = enabled_builtins.get(prefix.prefix, "")
+        if value:
+            status = terminal_color("fragment_enabled", "[enabled]")
+            print(f"  {prefix.prefix}/{value}  {status}  Sets {prefix.variable} = {value}")
+        else:
+            print(f"  {prefix.prefix}/...  [builtin]  Sets {prefix.variable} = <value>")
+    print()
+
+    # Group by layer
+    by_layer: Dict[str, List[Fragment]] = {}
+    for f in fragments:
+        by_layer.setdefault(f.layer, []).append(f)
+
+    for layer, layer_fragments in sorted(by_layer.items()):
+        print(f"Layer: {layer}")
+        for f in sorted(layer_fragments, key=lambda x: x.name):
+            if f.is_enabled:
+                status = terminal_color("fragment_enabled", "[enabled]")
+            else:
+                status = "[      ]"
+            if verbose:
+                print(f"  {f.name}")
+                if f.is_enabled:
+                    print(f"    Status: {terminal_color('fragment_enabled', 'Enabled')}")
+                else:
+                    print(f"    Status: Disabled")
+                print(f"    Path: {f.path}")
+                print(f"    Summary: {f.summary}")
+                if f.description:
+                    print(f"    Description: {f.description}")
+                print()
+            else:
+                print(f"  {status}  {f.name:<40}  {f.summary[:40]}")
+        print()
+
+
+def _show_fragment(name: str, fragments: List[Fragment]) -> int:
+    """Show content of a fragment."""
+    frag = next((f for f in fragments if f.name == name), None)
+
+    if not frag:
+        print(f"Fragment not found: {name}")
+        return 1
+
+    if not frag.path or not os.path.isfile(frag.path):
+        print(f"Fragment has no file: {name}")
+        return 1
+
+    print(f"Fragment: {frag.name}")
+    print(f"Path: {frag.path}")
+    print(f"Summary: {frag.summary}")
+    print()
+    print("-" * 60)
+    with open(frag.path, "r") as f:
+        print(f.read())
+
+    return 0
+
+
+# =============================================================================
+# Main Entry Point
+# =============================================================================
+
+def run_fragment(args) -> int:
+    """
+    Main entry point for fragment command.
+
+    Args:
+        args: Parsed command line arguments with:
+            - fragment_command: Subcommand (list, enable, disable, show)
+            - fragmentname: Fragment name(s) for enable/disable/show
+            - confpath: Path to toolcfg.conf
+            - verbose: Show descriptions in list mode
+    """
+    bblayers = getattr(args, "bblayers", None)
+    confpath = getattr(args, "confpath", None)
+    fragment_command = getattr(args, "fragment_command", None)
+    fragmentnames = getattr(args, "fragmentname", None)
+    verbose = getattr(args, "verbose", False)
+    list_mode = getattr(args, "list", False)
+
+    # Resolve bblayers.conf
+    bblayers_path = resolve_bblayers_path(bblayers)
+    if not bblayers_path:
+        print("No bblayers.conf found. Run from a Yocto/OE project directory.")
+        return 1
+
+    # Get layer paths
+    try:
+        layer_paths = extract_layer_paths(bblayers_path)
+    except SystemExit:
+        return 1
+
+    # Determine toolcfg.conf path
+    toolcfg_path = confpath or _get_toolcfg_path(bblayers_path)
+
+    # Get enabled fragments
+    enabled_list = _parse_enabled_fragments(toolcfg_path) if os.path.exists(toolcfg_path) else []
+
+    # Discover fragments
+    fragments = _discover_fragments(layer_paths)
+
+    # Mark enabled fragments
+    for f in fragments:
+        f.is_enabled = f.name in enabled_list
+
+    # Get builtin prefixes
+    builtin_prefixes = DEFAULT_BUILTIN_PREFIXES
+    enabled_builtins = _get_enabled_builtin_values(enabled_list, builtin_prefixes)
+
+    # Handle subcommands
+    if fragment_command == "list" or list_mode:
+        _list_fragments_text(fragments, builtin_prefixes, enabled_builtins, verbose)
+        return 0
+
+    if fragment_command == "enable":
+        if not fragmentnames:
+            print("No fragment names specified.")
+            return 1
+
+        # Validate fragments exist
+        valid_fragments = []
+        for name in fragmentnames:
+            # Check if it's a builtin prefix
+            prefix = name.split("/", 1)[0] if "/" in name else ""
+            is_builtin = prefix in {p.prefix for p in builtin_prefixes}
+
+            if is_builtin:
+                valid_fragments.append(name)
+            elif any(f.name == name for f in fragments):
+                valid_fragments.append(name)
+            else:
+                print(f"Fragment not found: {name}")
+                return 1
+
+        modified = _update_oe_fragments(toolcfg_path, valid_fragments, [], builtin_prefixes)
+        if modified:
+            for name in valid_fragments:
+                print(f"Enabled: {name}")
+                # Show summary for file fragments
+                frag = next((f for f in fragments if f.name == name), None)
+                if frag:
+                    print(f"  Summary: {frag.summary}")
+        return 0
+
+    if fragment_command == "disable":
+        if not fragmentnames:
+            print("No fragment names specified.")
+            return 1
+
+        modified = _update_oe_fragments(toolcfg_path, [], fragmentnames, builtin_prefixes)
+        if modified:
+            for name in fragmentnames:
+                print(f"Disabled: {name}")
+        return 0
+
+    if fragment_command == "show":
+        if not fragmentnames:
+            print("No fragment name specified.")
+            return 1
+        return _show_fragment(fragmentnames, fragments)
+
+    # Default: interactive browser
+    return _fragment_fzf_browser(fragments, builtin_prefixes, enabled_builtins, toolcfg_path)