machineconfig 6.82__py3-none-any.whl → 8.51__py3-none-any.whl

machineconfig/scripts/python/helpers/helpers_navigator/cli_graph_loader.py

@@ -0,0 +1,234 @@
+"""
+Load and normalize CLI graph data for the command navigator.
+"""
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+from typing import Any
+
+from machineconfig.scripts.python.helpers.helpers_navigator.data_models import (
+    CommandInfo,
+    ArgumentInfo,
+)
+
+
+DEFAULT_CLI_GRAPH_PATH = Path(__file__).resolve().parents[2] / "graph" / "cli_graph.json"
+
+
+@dataclass
+class CommandNode:
+    """Command info plus its children."""
+    info: CommandInfo
+    children: list["CommandNode"]
+
+
+def load_cli_graph(path: Path | None = None) -> dict[str, Any]:
+    """Load the CLI graph JSON file."""
+    graph_path = path or DEFAULT_CLI_GRAPH_PATH
+    with graph_path.open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def build_command_nodes(graph: dict[str, Any], *, include_root: bool = False) -> list[CommandNode]:
+    """Build command nodes from the CLI graph."""
+    root = graph.get("root", {})
+    root_name = root.get("name") if include_root else None
+    parent_tokens = [root_name] if root_name else []
+    children = root.get("children", [])
+    return [_build_node(child, parent_tokens, parent_name=root_name) for child in children]
+
+
+def _build_node(node: dict[str, Any], parent_tokens: list[str], parent_name: str | None) -> CommandNode:
+    kind = node.get("kind", "command")
+    name = node.get("name", "")
+    tokens = parent_tokens + ([name] if name else [])
+    command = " ".join(tokens).strip()
+    is_group = kind == "group"
+    description = _node_description(node)
+    long_description = _node_long_description(node, description)
+    module_path = _node_module_path(node)
+    arguments = _parse_signature(node.get("signature"))
+    help_text = _build_usage(command, arguments) if (command and not is_group) else ""
+
+    info = CommandInfo(
+        name=name,
+        description=description,
+        command=command,
+        parent=parent_name,
+        is_group=is_group,
+        help_text=help_text,
+        module_path=module_path,
+        arguments=arguments,
+        long_description=long_description,
+    )
+
+    children = [
+        _build_node(child, tokens, parent_name=name)
+        for child in node.get("children", [])
+    ]
+    return CommandNode(info=info, children=children)
+
+
+def _node_description(node: dict[str, Any]) -> str:
+    if node.get("kind") == "group":
+        return (
+            node.get("app", {}).get("help")
+            or node.get("help")
+            or node.get("doc")
+            or node.get("name", "")
+        )
+    return (
+        node.get("short_help")
+        or node.get("help")
+        or node.get("doc")
+        or node.get("name", "")
+    )
+
+
+def _node_long_description(node: dict[str, Any], fallback: str) -> str:
+    if node.get("kind") == "group":
+        return (
+            node.get("app", {}).get("help")
+            or node.get("help")
+            or node.get("doc")
+            or fallback
+        )
+    return node.get("help") or node.get("doc") or fallback
+
+
+def _node_module_path(node: dict[str, Any]) -> str:
+    source = node.get("source") or {}
+    return source.get("dispatches_to") or source.get("module") or ""
+
+
+def _parse_signature(signature: dict[str, Any] | None) -> list[ArgumentInfo]:
+    if not signature:
+        return []
+
+    arguments: list[ArgumentInfo] = []
+    for param in signature.get("parameters", []):
+        typer_info = param.get("typer") or {}
+        kind = typer_info.get("kind") or ""
+        name = param.get("name", "")
+        is_required = bool(param.get("required", False))
+        description = typer_info.get("help") or ""
+
+        if kind == "argument":
+            arguments.append(
+                ArgumentInfo(
+                    name=name,
+                    is_required=is_required,
+                    is_flag=False,
+                    placeholder=name,
+                    description=description,
+                    is_positional=True,
+                )
+            )
+            continue
+
+        if kind == "option":
+            flag, negated_flag = _select_flags(typer_info, name)
+            long_flags = list(typer_info.get("long_flags") or [])
+            short_flags = list(typer_info.get("short_flags") or [])
+            is_flag = _is_bool_type(param.get("type"))
+            arguments.append(
+                ArgumentInfo(
+                    name=name,
+                    is_required=is_required,
+                    is_flag=is_flag,
+                    placeholder=name,
+                    description=description,
+                    flag=flag,
+                    negated_flag=negated_flag,
+                    long_flags=long_flags,
+                    short_flags=short_flags,
+                )
+            )
+            continue
+
+    return arguments
+
+
+def _is_bool_type(type_value: Any) -> bool:
+    if type_value is None:
+        return False
+    normalized = str(type_value).replace(" ", "").lower()
+    return "bool" in normalized
+
+
+def _select_flags(typer_info: dict[str, Any], name: str) -> tuple[str, str]:
+    long_flags = list(typer_info.get("long_flags") or [])
+    short_flags = list(typer_info.get("short_flags") or [])
+    param_decls = list(typer_info.get("param_decls") or [])
+
+    candidates = long_flags or _split_param_decls(param_decls)
+    if not candidates and short_flags:
+        candidates = short_flags
+
+    flag, negated_flag = _pick_positive_negative(candidates)
+    if not flag:
+        flag = _default_flag(name)
+
+    return flag, negated_flag
+
+
+def _split_param_decls(param_decls: list[str]) -> list[str]:
+    candidates: list[str] = []
+    for decl in param_decls:
+        parts = [part.strip() for part in decl.split("/") if part.strip()]
+        candidates.extend(parts)
+    return candidates
+
+
+def _pick_positive_negative(flags: list[str]) -> tuple[str, str]:
+    if not flags:
+        return "", ""
+
+    positives = [flag for flag in flags if not _is_negative_flag(flag)]
+    negatives = [flag for flag in flags if _is_negative_flag(flag)]
+
+    if positives:
+        return positives[0], negatives[0] if negatives else ""
+
+    return flags[0], ""
+
+
+def _is_negative_flag(flag: str) -> bool:
+    token = flag.lstrip("-")
+    return token.startswith("no-")
+
+
+def _default_flag(name: str) -> str:
+    return f"--{name.replace('_', '-')}"
+
+
+def _build_usage(command: str, arguments: list[ArgumentInfo]) -> str:
+    if not arguments:
+        return command
+
+    parts = [command]
+    for arg in arguments:
+        if arg.is_positional:
+            token = f"<{arg.name}>"
+            if not arg.is_required:
+                token = f"[{token}]"
+            parts.append(token)
+            continue
+
+        flag = arg.flag or _default_flag(arg.name)
+        if arg.is_flag:
+            if arg.negated_flag:
+                token = f"[{flag}|{arg.negated_flag}]"
+            else:
+                token = f"[{flag}]"
+            parts.append(token)
+            continue
+
+        placeholder = arg.placeholder or arg.name
+        token = f"{flag} <{placeholder}>"
+        if not arg.is_required:
+            token = f"[{token}]"
+        parts.append(token)
+
+    return " ".join(parts)

machineconfig/scripts/python/{helpers_navigator → helpers/helpers_navigator}/command_builder.py

@@ -7,7 +7,7 @@ from textual.app import ComposeResult
 from textual.containers import Horizontal, VerticalScroll
 from textual.widgets import Static, Input, Label, Button
 from textual.screen import ModalScreen
-from machineconfig.scripts.python.helpers_navigator.data_models import CommandInfo, ArgumentInfo
+from machineconfig.scripts.python.helpers.helpers_navigator.data_models import CommandInfo, ArgumentInfo
 
 
 class CommandBuilderScreen(ModalScreen[str]):
@@ -16,7 +16,11 @@ class CommandBuilderScreen(ModalScreen[str]):
     def __init__(self, command_info: CommandInfo) -> None:
         super().__init__()
         self.command_info = command_info
-        self.arguments = self._parse_arguments()
+        self.arguments = (
+            command_info.arguments
+            if command_info.arguments is not None
+            else self._parse_arguments()
+        )
         self.input_widgets: dict[str, Input] = {}
 
     def _parse_arguments(self) -> list[ArgumentInfo]:
@@ -34,21 +38,40 @@ class CommandBuilderScreen(ModalScreen[str]):
             arg_name = match.group(1)
             placeholder = match.group(2)
             if arg_name not in seen_names:
-                args.append(ArgumentInfo(name=arg_name, is_required=False, is_flag=False, placeholder=placeholder))
+                args.append(ArgumentInfo(
+                    name=arg_name,
+                    is_required=False,
+                    is_flag=False,
+                    placeholder=placeholder,
+                    flag=f"--{arg_name}",
+                    long_flags=[f"--{arg_name}"],
+                ))
                 seen_names.add(arg_name)
 
         flag_pattern = re.compile(r'--(\w+(?:-\w+)*)(?:\s|$)')
         for match in flag_pattern.finditer(help_text):
             arg_name = match.group(1)
             if arg_name not in seen_names:
-                args.append(ArgumentInfo(name=arg_name, is_required=False, is_flag=True))
+                args.append(ArgumentInfo(
+                    name=arg_name,
+                    is_required=False,
+                    is_flag=True,
+                    flag=f"--{arg_name}",
+                    long_flags=[f"--{arg_name}"],
+                ))
                 seen_names.add(arg_name)
 
         positional_pattern = re.compile(r'<(\w+)>(?!\s*>)')
         for match in positional_pattern.finditer(help_text):
             arg_name = match.group(1)
             if arg_name not in seen_names and not re.search(rf'--\w+\s+<{arg_name}>', help_text):
-                args.append(ArgumentInfo(name=arg_name, is_required=True, is_flag=False, placeholder=arg_name))
+                args.append(ArgumentInfo(
+                    name=arg_name,
+                    is_required=True,
+                    is_flag=False,
+                    placeholder=arg_name,
+                    is_positional=True,
+                ))
                 seen_names.add(arg_name)
 
         return args
@@ -63,12 +86,22 @@ class CommandBuilderScreen(ModalScreen[str]):
             else:
                 for arg in self.arguments:
                     if arg.is_flag:
-                        label_text = f"--{arg.name} (flag, leave empty to skip)"
+                        flag = arg.flag or f"--{arg.name}"
+                        if arg.negated_flag:
+                            label_text = f"{flag} / {arg.negated_flag} (flag, leave empty to skip)"
+                        else:
+                            label_text = f"{flag} (flag, leave empty to skip)"
                         yield Label(label_text)
                         input_widget = Input(placeholder="yes/no or leave empty", id=f"arg_{arg.name}")
+                    elif arg.is_positional:
+                        required_marker = "[red]*[/red]" if arg.is_required else "[dim](optional)[/dim]"
+                        label_text = f"{arg.name} {required_marker}"
+                        yield Label(label_text)
+                        input_widget = Input(placeholder=arg.placeholder or arg.name, id=f"arg_{arg.name}")
                     else:
+                        flag = arg.flag or f"--{arg.name}"
                         required_marker = "[red]*[/red]" if arg.is_required else "[dim](optional)[/dim]"
-                        label_text = f"--{arg.name} {required_marker}"
+                        label_text = f"{flag} {required_marker}"
                         yield Label(label_text)
                         input_widget = Input(placeholder=arg.placeholder or arg.name, id=f"arg_{arg.name}")
 
@@ -96,16 +129,31 @@ class CommandBuilderScreen(ModalScreen[str]):
     def _build_command(self) -> str:
         """Build the complete command with arguments."""
         parts = [self.command_info.command]
+        yes_values = {"yes", "y", "true", "1", "on"}
+        no_values = {"no", "n", "false", "0", "off"}
 
         for arg in self.arguments:
             input_widget = self.input_widgets.get(arg.name)
             if input_widget:
                 value = input_widget.value.strip()
                 if value:
-                    if arg.is_flag:
-                        if value.lower() in ('yes', 'y', 'true', '1'):
-                            parts.append(f"--{arg.name}")
-                    else:
-                        parts.append(f"--{arg.name} {value}")
+                    if arg.is_positional:
+                        parts.append(value)
+                        continue
 
-        return " ".join(parts)
+                    if arg.is_flag:
+                        flag_value = value.lower()
+                        flag = arg.flag or f"--{arg.name}"
+                        if flag_value in yes_values:
+                            parts.append(flag)
+                        elif flag_value in no_values:
+                            if arg.negated_flag:
+                                parts.append(arg.negated_flag)
+                        elif value.startswith("-"):
+                            parts.append(value)
+                        continue
+
+                    flag = arg.flag or f"--{arg.name}"
+                    parts.append(f"{flag} {value}")
+
+        return " ".join(parts)

machineconfig/scripts/python/helpers/helpers_navigator/command_detail.py

@@ -0,0 +1,153 @@
+"""
+Command detail widget for displaying command information.
+"""
+
+from typing import Optional
+from textual.widgets import Static
+from rich.text import Text
+from rich.panel import Panel
+from rich.console import Group
+from rich.table import Table
+from rich import box
+from machineconfig.scripts.python.helpers.helpers_navigator.data_models import CommandInfo
+
+
+class CommandDetail(Static):
+    """Widget for displaying command details."""
+
+    def __init__(self, *, id: str) -> None:  # type: ignore
+        super().__init__(id=id)
+        self.command_info: Optional[CommandInfo] = None
+
+    def update_command(self, command_info: Optional[CommandInfo]) -> None:
+        """Update displayed command information."""
+        self.command_info = command_info
+        if command_info is None:
+            self.update("Select a command to view details")
+            return
+
+        if command_info.is_group:
+            self.update(self._render_group(command_info))
+            return
+
+        self.update(self._render_command(command_info))
+
+    def _render_group(self, command_info: CommandInfo) -> Panel:
+        content = Text()
+        content.append("Group: ", style="bold cyan")
+        content.append(f"{command_info.name}\n\n", style="bold yellow")
+
+        content.append("Description: ", style="bold green")
+        content.append(f"{command_info.long_description or command_info.description}\n\n", style="white")
+
+        content.append("Command: ", style="bold blue")
+        content.append(f"{command_info.command}\n\n", style="bold white")
+
+        if command_info.module_path:
+            content.append("Module: ", style="bold red")
+            content.append(f"{command_info.module_path}\n", style="white")
+
+        return Panel(content, title=f"[bold]{command_info.name}[/bold]", border_style="blue")
+
+    def _render_command(self, command_info: CommandInfo) -> Panel:
+        renderables = []
+        usage_text = Text()
+        usage_text.append("Usage: ", style="bold cyan")
+        usage_text.append(self._format_usage(command_info), style="white")
+        renderables.append(usage_text)
+
+        description = command_info.long_description or command_info.description
+        if description:
+            renderables.append(Text(description, style="green"))
+
+        arguments = command_info.arguments or []
+        positional_args = [arg for arg in arguments if arg.is_positional]
+        option_args = [arg for arg in arguments if not arg.is_positional]
+
+        if positional_args:
+            renderables.append(self._build_arguments_table(positional_args))
+
+        renderables.append(self._build_options_table(option_args))
+
+        if command_info.module_path:
+            renderables.append(Text(f"Module: {command_info.module_path}", style="dim"))
+
+        content = Group(*renderables)
+        return Panel(content, title=f"[bold]{command_info.name}[/bold]", border_style="blue")
+
+    def _format_usage(self, command_info: CommandInfo) -> str:
+        arguments = command_info.arguments or []
+        positional_args = [arg for arg in arguments if arg.is_positional]
+        option_args = [arg for arg in arguments if not arg.is_positional]
+
+        parts = [command_info.command or command_info.name]
+        if option_args:
+            parts.append("[OPTIONS]")
+
+        for arg in positional_args:
+            placeholder = self._placeholder(arg)
+            token = placeholder if arg.is_required else f"[{placeholder}]"
+            parts.append(token)
+
+        usage = " ".join(parts).strip()
+        return usage or command_info.help_text or command_info.name
+
+    def _build_arguments_table(self, arguments) -> Table:  # type: ignore
+        table = Table(box=box.MINIMAL, show_header=False, pad_edge=False)
+        table.add_column("Argument", style="bold cyan", no_wrap=True)
+        table.add_column("Description", style="white")
+
+        for arg in arguments:
+            placeholder = self._placeholder(arg)
+            token = f"{arg.name} {placeholder}" if arg.is_required else f"{arg.name} [{placeholder}]"
+            table.add_row(token, arg.description or "")
+
+        table.title = "Arguments"
+        table.title_style = "bold green"
+        return table
+
+    def _build_options_table(self, options) -> Table:  # type: ignore
+        table = Table(box=box.MINIMAL, show_header=False, pad_edge=False)
+        table.add_column("Option", style="bold cyan", no_wrap=True)
+        table.add_column("Description", style="white")
+
+        for opt in options:
+            flag_text = self._format_option_flags(opt)
+            if not opt.is_flag:
+                placeholder = self._placeholder(opt)
+                flag_text = f"{flag_text} <{placeholder}>"
+            table.add_row(flag_text, opt.description or "")
+
+        table.add_row("--help", "Show this message and exit.")
+        table.title = "Options"
+        table.title_style = "bold magenta"
+        return table
+
+    def _format_option_flags(self, arg) -> str:  # type: ignore
+        parts = []
+        if arg.long_flags:
+            parts.append(self._combine_flags(arg.long_flags))
+        if arg.short_flags:
+            parts.append(self._combine_flags(arg.short_flags))
+
+        if not parts:
+            if arg.flag and arg.negated_flag:
+                parts.append(f"{arg.flag} / {arg.negated_flag}")
+            elif arg.flag:
+                parts.append(arg.flag)
+            else:
+                parts.append(f"--{arg.name.replace('_', '-')}")
+
+        return ", ".join(parts)
+
+    def _combine_flags(self, flags) -> str:  # type: ignore
+        if len(flags) == 2 and self._is_negative_flag(flags[1]) and not self._is_negative_flag(flags[0]):
+            return f"{flags[0]} / {flags[1]}"
+        return ", ".join(flags)
+
+    def _is_negative_flag(self, flag: str) -> bool:
+        token = flag.lstrip("-")
+        return token.startswith("no-")
+
+    def _placeholder(self, arg) -> str:  # type: ignore
+        return (arg.placeholder or arg.name).upper()

machineconfig/scripts/python/helpers/helpers_navigator/command_tree.py

@@ -0,0 +1,45 @@
+"""
+Command tree widget for displaying command hierarchy.
+"""
+
+from textual.widgets import Tree
+
+from machineconfig.scripts.python.helpers.helpers_navigator.cli_graph_loader import (
+    CommandNode,
+    build_command_nodes,
+    load_cli_graph,
+)
+from machineconfig.scripts.python.helpers.helpers_navigator.data_models import CommandInfo
+
+
+class CommandTree(Tree[CommandInfo]):
+    """Tree widget for displaying command hierarchy."""
+
+    def on_mount(self) -> None:
+        """Build the command tree when mounted."""
+        self.show_root = False
+        self.guide_depth = 2
+        self._build_command_tree()
+
+    def _build_command_tree(self) -> None:
+        """Build the hierarchical command structure from the CLI graph."""
+        try:
+            graph = load_cli_graph()
+            nodes = build_command_nodes(graph)
+        except Exception as exc:
+            self.root.add(f"Error loading CLI graph: {exc}", data=None)
+            return
+
+        for node in nodes:
+            self._add_command_node(self.root, node)
+
+    def _add_command_node(self, parent, node: CommandNode) -> None:  # type: ignore
+        label = self._format_label(node.info)
+        tree_node = parent.add(label, data=node.info)
+        for child in node.children:
+            self._add_command_node(tree_node, child)
+
+    def _format_label(self, info: CommandInfo) -> str:
+        if info.description and info.description != info.name:
+            return f"{info.name} - {info.description}"
+        return info.name

machineconfig/scripts/python/{helpers_navigator → helpers/helpers_navigator}/data_models.py

@@ -3,7 +3,22 @@ Data models for the command navigator.
 """
 
 from typing import Optional
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ArgumentInfo:
+    """Information about a command argument."""
+    name: str
+    is_required: bool
+    is_flag: bool
+    placeholder: str = ""
+    description: str = ""
+    is_positional: bool = False
+    flag: str = ""
+    negated_flag: str = ""
+    long_flags: list[str] = field(default_factory=list)
+    short_flags: list[str] = field(default_factory=list)
 
 
 @dataclass
@@ -16,13 +31,5 @@ class CommandInfo:
     is_group: bool = False
     help_text: str = ""
     module_path: str = ""
-
-
-@dataclass
-class ArgumentInfo:
-    """Information about a command argument."""
-    name: str
-    is_required: bool
-    is_flag: bool
-    placeholder: str = ""
-    description: str = ""
+    arguments: Optional[list[ArgumentInfo]] = None
+    long_description: str = ""

machineconfig/scripts/python/{helpers_navigator → helpers/helpers_navigator}/main_app.py

@@ -6,11 +6,11 @@ import subprocess
 from textual.app import App, ComposeResult
 from textual.widgets import Header, Footer, Input, Tree
 from textual.binding import Binding
-from machineconfig.scripts.python.helpers_navigator.command_builder import CommandBuilderScreen
-from machineconfig.scripts.python.helpers_navigator.command_tree import CommandTree
-from machineconfig.scripts.python.helpers_navigator.command_detail import CommandDetail
-from machineconfig.scripts.python.helpers_navigator.search_bar import SearchBar
-from machineconfig.scripts.python.helpers_navigator.data_models import CommandInfo
+from machineconfig.scripts.python.helpers.helpers_navigator.command_builder import CommandBuilderScreen
+from machineconfig.scripts.python.helpers.helpers_navigator.command_tree import CommandTree
+from machineconfig.scripts.python.helpers.helpers_navigator.command_detail import CommandDetail
+from machineconfig.scripts.python.helpers.helpers_navigator.search_bar import SearchBar
+from machineconfig.scripts.python.helpers.helpers_navigator.data_models import CommandInfo
 
 
 class CommandNavigatorApp(App[None]):