#!/usr/bin/python3.13
##################################################################################
#                                                                                #
# Odin Shell                                                                     #
#                                                                                #
# Author      : Sean M. Watkins, Senior Staff Software Engineer                  #
# Copyright   : 2025 Cohesity Inc.                                               #
# Contact     : swatkins@cohesity.com                                            #
# Description : This is a pure API implementation of the Odin Debug Shell in the #
#               base cohesity platform.                                          #
#                                                                                #
##################################################################################
__docformat__ = "google"

import builtins
import os
import argparse
import pathlib
import shlex
import sys
import time
import cmd2
import re
import json
import gnureadline as readline
import pandas as pd
import subprocess
import httpx
from datetime import datetime

from multiprocessing.pool import AsyncResult
from multiprocessing.pool import ThreadPool as tp

from rich import print
from rich.table import Table, Column
from rich.box import ROUNDED, SIMPLE
from rich.prompt import Prompt
from rich.style import Style
from rich.rule import Rule
from rich.console import Group
from rich.progress import Progress, BarColumn, TextColumn, TimeElapsedColumn, SpinnerColumn
from rich.spinner import Spinner
from rich.console import Console
from rich.markdown import Markdown
from rich.live import Live
from rich.panel import Panel
from rich.layout import Layout
from rich.text import Text
from rich.align import Align

import lib.odin_shell_constants as Constants
from lib.odin_shell_cli_print import stCliPrint
from lib.odin_shell_util_organizer import OrganizeUtil
from lib.odin_shell_crypto import stCrypto
from cryptography.fernet import Fernet
from lib.odin_shell_rest_infra import stRestInfra
from lib.odin_shell_iris_service import IrisService
from lib.odin_shell_logger import OdinLogger as Logger

#Override the builtins print to use rich print
builtins.print = print

stLogger = Logger.get_instance()

class secureDebug(cmd2.Cmd):

    def __init__(self,kwargs:dict[str, str]) -> None:
        """Initialize the secureDebug shell.

        Args:
            kwargs (dict[str, str]): Initialization parameters.
        """
        super().__init__(allow_redirection=False,
                         allow_cli_args=False)
        # Break out kwargs
        self.localIP:str = self.get_local_ip()
        self.test = kwargs.get('dev', False)
        # Initialize the cryptography library
        self.all:bool = False
        self.crypto:stCrypto = stCrypto()
        # Initialize the rest_infra library and wait for the API to be ready
        self.rest_infra:stRestInfra = None
        self.org_util:OrganizeUtil = None
        self._wait_for_api()
        # Initialize the CLI print utility
        self.cli_print:stCliPrint = stCliPrint()
        self.iris:IrisService = None
        # Initialize a console for rich text printing (force truecolor for SSH sessions)
        self.console = Console(color_system="truecolor", force_terminal=True)
        self.stdout = self.console.file
        # Init Modules
        self.modules:dict[str, list[str]] = {}
        self.runMod:list[str] = None #self.rest_infra.get_run_modules()
        # Define Available Commands
        self.commands:list[str] = ['list','run','get','iris','manual','refresh',
                                   'version','release_notes',
                                   'history','clear','exit','quit']
        # Setup initial prompt, intro and header
        self.prompt = f'(\033[34mOdin Shell\033[0m) : '
        self.ruler = '-'
        # Initialize histfile and size
        self.histfile = Constants.HIST_FILE
        self.histfile_size = Constants.HIST_SIZE
        # Initialize the threadpool
        self.pool = tp(processes=min(4, os.cpu_count() or 1))
        # Define XR Runtime Dictionary, used to track async jobs
        self.xr_runs : dict[str,str] = {}
        # Cache for tab-completion of run IDs: (timestamp, [run_id, ...])
        self._result_cache: tuple[float, list] = (0.0, [])
        # Cache for tab-completion of module/utility names: (timestamp, (modules, util_map))
        self._module_cache: tuple[float, tuple] = (0.0, ([], {}))
        # Debug mode flag (set by run --debug)
        self.debug_mode: bool = False
        try:
            self.util_list:list[str] = None #self.build_list()
            self.moduleUtilName:dict[str, list[str]] = None #self.modToUtilName()
        except Exception as e:
            print(f"[red]Error[/] : Exception building module utility names \n[red]Error[/] : {e}[/]")
            sys.exit(1)
        # Shell Command Clenup and error resolution
        del cmd2.Cmd.do_edit
        del cmd2.Cmd.do_alias
        del cmd2.Cmd.do_macro
        del cmd2.Cmd.do_run_pyscript
        del cmd2.Cmd.do_run_script
        del cmd2.Cmd.do_set
        del cmd2.Cmd.do_shortcuts
        del cmd2.Cmd.do_shell
        cmd2.exceptions.CompletionError(apply_style=False)
        cmd2.exceptions.SkipPostcommandHooks()


    def _wait_for_api(self, poll_interval: int = 5, max_wait: int = 300) -> None:
        """
        Wait for the Odin API service to become available.

        Polls the API status endpoint every ``poll_interval`` seconds with a
        lightweight httpx probe (no singleton side-effects).  Only once the
        probe succeeds does it build the full stRestInfra + OrganizeUtil.
        Exits cleanly after ``max_wait`` seconds if the service never responds.

        Args:
            poll_interval (int): Seconds between retries. Default 5.
            max_wait (int): Maximum seconds to wait before giving up. Default 300.
        """
        console = Console(color_system="truecolor", force_terminal=True)
        url = f"https://{self.localIP}:27015"
        start = time.time()
        # Mutable cell so closures can update the last probe result for display
        _last_response: list[str] = ["connecting…"]

        def _probe() -> bool:
            """Cheap liveness check — does NOT touch the stRestInfra singleton."""
            try:
                with httpx.Client(verify=False, timeout=5,
                                  headers={"Content-Type": "application/json"}) as c:
                    r = c.get(f"{url}/client/status")
                    if r.status_code == 200:
                        _last_response[0] = "HTTP 200 OK"
                        return True
                    _last_response[0] = f"HTTP {r.status_code}"
                    return False
            except Exception as exc:
                _last_response[0] = f"{type(exc).__name__}: {exc}"
                return False

        def _full_init() -> bool:
            """Build stRestInfra + OrganizeUtil now that the API is confirmed up."""
            try:
                existing = stRestInfra.get_instance(url)
                if existing is not None:
                    existing.close()
                rest = stRestInfra.get_instance(url)
                if rest is None:
                    return False
                self.rest_infra = rest
                OrganizeUtil.reset_instance()
                self.org_util = OrganizeUtil(test=self.test, refresh=False)
                return True
            except Exception:
                return False

        # Fast first attempt before showing the spinner
        if _probe() and _full_init():
            return

        def _build_panel(initialising: bool = False) -> Group:
            """Build a status panel styled like hc_cli status."""
            tbl = Table(
                show_header=True, header_style="bold cyan",
                box=SIMPLE, padding=(0, 3),
                show_edge=False, leading=1,
            )
            tbl.add_column("Property",  style="dim",   no_wrap=True, min_width=16)
            tbl.add_column("Value",     style="white",  no_wrap=False)

            if initialising:
                status_cell = Text("Initialising shell…", style="bold green")
            else:
                status_cell = Spinner("dots", text=Text("Waiting for API…", style="bold yellow"))

            last = _last_response[0]
            if last in ("connecting…", "HTTP 200 OK"):
                last_cell = Text(last, style="dim")
            else:
                last_cell = Text(last, style="bold red")

            tbl.add_row("Endpoint",      Text(f"{url}/client/status", style="cyan"))
            tbl.add_row("Status",        status_cell)
            tbl.add_row("Last Response", last_cell)

            panel = Panel(
                tbl,
                title="[bold cyan]Odin Shell — Waiting for API[/bold cyan]",
                subtitle="[dim]Ctrl-C  to abort[/dim]",
                border_style="cyan",
                expand=False,
                padding=(1, 4),
            )
            return Group(Text(""), panel, Text(""))

        try:
            with Live(Align.center(_build_panel()), console=console,
                      refresh_per_second=20, transient=True) as live:
                while True:
                    elapsed = time.time() - start
                    if elapsed >= max_wait:
                        console.print(
                            f"\n[red]API service did not respond within {max_wait} seconds.[/]"
                            " Please check that the Odin daemon is running.\n"
                        )
                        sys.exit(1)
                    time.sleep(poll_interval)
                    live.update(Align.center(_build_panel()))
                    if _probe():
                        live.update(Align.center(_build_panel(initialising=True)))
                        if _full_init():
                            break
                        # probe succeeded but singleton init failed — keep waiting
        except KeyboardInterrupt:
            console.print("\n[yellow]Startup interrupted by user.[/]\n")
            sys.exit(0)

    def get_local_ip(self) -> str:
        """Fetches the local IP address of the current node.

        Uses ``ip route show default`` and extracts the gateway IP from
        the ``default via <IP>`` field, which is the host machine's
        network address used to reach brigid's REST API.

        Returns:
            str: The local IP address.
        """
        command = ['ip', 'route', 'show', 'default']
        result = subprocess.run(command, capture_output=True, text=True)
        ip_output = result.stdout.strip()
        stLogger.debug(f'ip route show default output: {repr(ip_output)}')

        ip_match = re.search(r'default via\s+(\d+\.\d+\.\d+\.\d+)', ip_output)
        if not ip_match:
            # Fallback: older iproute2 versions may omit "default" or use a
            # slightly different format — try matching any "via <IP>" token.
            ip_match = re.search(r'\bvia\s+(\d+\.\d+\.\d+\.\d+)', ip_output)
            if ip_match:
                stLogger.debug('Primary "default via" regex missed; matched via fallback "via <IP>" pattern')
        if ip_match:
            local_ip = ip_match.group(1)
            stLogger.info(f'Local IP address determined as {local_ip}')
        else:
            stLogger.warning(
                f'Could not parse "default via" IP from "ip route show default" output: {repr(ip_output)} — '
                f'falling back to 127.0.0.1'
            )
            local_ip = '127.0.0.1'

        try:
            url = f'https://{local_ip}:27015/client/status'
            stLogger.debug(f'Validating local IP via GET {url}')
            with httpx.Client(verify=False,
                              timeout=5,
                              headers={'Connection': 'close',
                                       'Content-Type': 'application/json'}) as session:
                response = session.get(url)
            if response.status_code != 200:
                stLogger.warning(
                    f'Validation GET {url} returned HTTP {response.status_code} — '
                    f'API not yet ready, returning routing-table IP anyway'
                )
            else:
                stLogger.info(f'Local IP {local_ip} validated successfully (HTTP {response.status_code})')
            return local_ip
        except Exception as e:
            stLogger.warning(
                f'Validation GET https://{local_ip}:27015/client/status failed: '
                f'{type(e).__name__}: {e} — API not yet ready, returning routing-table IP anyway'
            )
            return local_ip
        

    def preloop(self):
        """
        preloop initalizes and handles all pre shell initailization functions

        Currently only handles the history file creation if not present
        """
        try:
            if readline and pathlib.Path(self.histfile).exists():
                readline.read_history_file(self.histfile)
            else:
                with open(self.histfile, 'wb'):
                    pass
                readline.read_history_file(self.histfile)
        except Exception:
            pass


    def postloop(self):
        """
        postloop executes on close of shell

        Currently trims history and writes to file
        """
        try:
            if readline:
                readline.set_history_length(self.histfile_size)
                readline.write_history_file(self.histfile)
        except Exception:
            pass
        try:
            self.pool.terminate()
            self.pool.join()
        except Exception:
            pass


    def precmd(self, line):
        """
        precmd executes prior to the command being run

        Current implementation logs the command being executed.

        Args:
            line (String): full line of the command being called

        Returns:
            string: The command entered, no modifications currently
        """
        stLogger.info(f'Input Command : {line}')
        return cmd2.Cmd.precmd(self, line)


    def do_history(self,line):
        """Print command history

        Args:
            line (string): Not used
        """
        if readline:
            num = 1
            for i in range(1, readline.get_current_history_length() + 1):
                print(f'{num:4}  {readline.get_history_item(i)}')
                num += 1

    def help_history(self) -> None:
        """Display help information for the history command."""
        print("""
        [yellow]Usage[/]:
            history

        [blue]Description[/]:
            Displays a numbered list of all commands entered during the current
            Odin Shell session.  History is maintained by GNU readline and
            persists only for the lifetime of the session.

        [magenta]Examples[/]:

            ([blue]Odin Shell[/]) : history

               1  list
               2  run shellRunner getClusterInfo
               3  version
               4  history
        """)

    def all_complete(self, text:str=None, line:str=None) -> list[str]:
        """
        all_complete attempts to guess and tab complete the line

        This function is used by both the list and run commands to provide
        tab completion for modules and utilities.

        Args:
            text (str, optional): The text to complete.
            line (str, optional): The current command line.

        Returns:
            list[str]: A list of possible completions.
        """
        result = []
        line = line.split()
        modules = list(self.org_util.utilDataClass.modules.to_dict()['Module Name'].values())
        utilities_raw = [fd["Name"].tolist() for fd in self.org_util.utilDataClass.module_util.values()]
        utilities = [u for sublist in utilities_raw for u in sublist]
        r = re.compile(text)
        # If length of the line is 1 or the second word is not a module
        if len(line) == 1 or (len(line) > 1 and line[1] not in modules):
            result = list(filter(r.match, modules))
        # If the second word is a module and either only two words or the third is not a utility
        elif (len(line) > 1 and line[1] in modules) and (len(line) == 2 or (len(line) > 2 and line[2] not in utilities)):
            utilities = self.org_util.utilDataClass.module_util[line[1]]['Name'].tolist()
            result = list(filter(r.match, utilities))
        # If result is 1, strip quotes (if needed)
        if len(result) == 1:
            result = [result[0].strip('\"')]
        return result


    def get_status(self):
        """
        Fetches the current status from the /master/status endpoint.
        Returns the parsed JSON or None.
        """
        data, err, code = self.rest_infra.sif_request(uri=self.rest_infra.valid_uri.get("get_master_status"), 
                                                      method="GET")
        if code == 200 and data:
            return data
        return None

    
    def do_refresh(self,line):
        """
        do_refresh refreshes the module and utility list from the API

        Args:
            line (String): Full command entered to the shell
        """
        if line == 'help':
            self.help_refresh()
            return
        self.org_util.reset_instance()
        self.org_util:OrganizeUtil = OrganizeUtil(test=self.test, refresh=True)
        print(f"\n[green]Module and Utility list refreshed from API[/]\n")
    

    def help_refresh(self):
        """Display help information for the refresh command."""
        print("""
        [yellow]Usage[/]:
            refresh

        [blue]Description[/]:
            Refreshes the module and utility list from the Sif API.
            Use this after new utilities have been deployed to pick up any additions
            without restarting the shell.

        [magenta]Examples[/]:

            ([blue]Odin Shell[/]) : refresh

            Module and Utility list refreshed from API
        """)

    def do_iris(self, line, valid=False):
        """Manage the Iris session via subcommands.

        Subcommands:
            iris login   — Authenticate and store credentials (default when no sub given).
            iris shell   — Authenticate if needed, then drop into iris_cli.
            iris logout  — Clear stored credentials and tear down the session.

        Args:
            line (str): Subcommand (login | shell | logout) plus optional extra args.
            valid (bool): Internal flag — skips repeated-login guard when True.
        """
        # Temporarily disable readline history while collecting credentials
        hist_len = 0
        if readline:
            try:
                hist_len = readline.get_current_history_length()
            except Exception:
                hist_len = 0

        if line == 'help':
            self.help_iris()
            return

        parts = shlex.split(line) if line else []
        sub   = parts[0].lower() if parts else 'login'

        # ── iris shell ───────────────────────────────────────────────────────
        if sub == 'shell':
            if self.iris is None:
                self.do_iris('login')
            creds = self.crypto.handle_creds(method="decrypt")
            if not creds or any(v is None for v in creds.values()):
                self.iris = None
                self.do_iris('login')
                creds = self.crypto.handle_creds(method="decrypt")
            command = [
                'iris_cli', '--skip_password_prompt=true',
                f"--username={creds['username']}",
                f"--password={creds['password']}",
                f"--domain={creds['domain']}",
            ]
            subprocess.run(command)
            return

        # ── iris logout ──────────────────────────────────────────────────────
        if sub == 'logout':
            try:
                if self.iris is not None:
                    self.iris.clear()
                    self.iris = None
                print("\n[green]Iris credentials cleared.[/]  "
                      "Use [yellow]iris login[/] or [yellow]iris shell[/] to re-authenticate.\n")
            except Exception as e:
                print(f"\n[red]Error resetting session[/] : {e}\n")
            return

        # ── iris login (default) ─────────────────────────────────────────────
        if self.iris is not None:
            if valid:
                return
            print('[yellow]Iris session already active.[/]  '
                  'Use [yellow]iris logout[/] to clear credentials.\n')
            return
        while True:
            domain = Prompt.ask('[yellow]Please enter [/][red] Domain [/] [yellow](If LOCAL leave blank)[/] ')
            if not domain:
                domain = 'LOCAL'
                self.crypto.creds['domain'] = domain
            print(f'\nDomain : {domain}\n')
            username = Prompt.ask('[yellow]Please enter [/][red]Iris Admin[/] [yellow]User[/] ')
            self.crypto.creds['username'] = username
            print(f'\nDomain : {domain} | User : {username}\n')
            password = Prompt.ask(f'[yellow]Please enter [/][blue]{username}[/] [yellow]Password[/] ', password=True)
            self.crypto.creds['password'] = password
            self.crypto.handle_creds(method='encrypt')
            print('')
            try:
                self.iris = IrisService.get_instance(username, password, domain, self.localIP)
                if self.iris.token is not None:
                    print('[green]Login Successful[/]\n')
                    break
                else:
                    print('[red]Invalid username or password[/]\n')
                    self.iris.clear()
            except Exception:
                print('[yellow]Iris logged in already[/]\n')
                return
        # Remove any lines added to history during credential input
        if readline:
            try:
                new_hist_len = readline.get_current_history_length()
                for _ in range(new_hist_len - hist_len):
                    readline.remove_history_item(hist_len)
            except Exception:
                pass


    def complete_iris(self, text, line, begidx, endidx) -> list[str]:
        """Tab-complete iris subcommands."""
        subs = ['login', 'shell', 'logout']
        if text:
            return [s for s in subs if s.startswith(text)]
        return subs


    def help_iris(self) -> None:
        """Display help information for the iris command."""
        print("""
        [yellow]Usage[/]:
            iris [login|shell|logout]

        [blue]Description[/]:
            Manage the Iris session.  Three subcommands are available:

            [cyan]iris login[/]   Prompts for Iris credentials and stores them encrypted in memory
                         for 30 minutes.  Equivalent to the bare [yellow]iris[/] command.

            [cyan]iris shell[/]   Authenticates (if needed) and drops you into an interactive
                         [bold]iris_cli[/] session.

            [cyan]iris logout[/]  Clears all stored credentials and tears down the active session.
                         The next [yellow]iris login[/] or [yellow]iris shell[/] will prompt for fresh creds.

        [magenta]Notes[/]:
            • Credentials are stored encrypted in memory and valid for [yellow]30 minutes[/].

        [magenta]Examples[/]:

            ([blue]Odin Shell[/]) : iris login

            Please enter Domain (If LOCAL leave blank) :
            Please enter Iris Admin User     : admin
            Please enter admin Password      : ••••••••
            Login Successful

            ([blue]Odin Shell[/]) : iris shell

            > (iris_cli interactive prompt)

            ([blue]Odin Shell[/]) : iris logout

            Iris credentials cleared.
        """)

    def do_version(self,line:str) -> None:
        """Display the version information.

        Args:
            line (str): The command line input.
        """
        version,err,code = self.rest_infra.sif_request(uri=self.rest_infra.valid_uri["get_version"])
        if code != 200:
            print(f"\n[red]Error retrieving version info[/] : {err}\n")
            return
        version_pd_list = []
        for key in version:
            version_pd_list.append([key,version[key]])
            version_pd = pd.DataFrame(version_pd_list, columns=['Component','Version'])
        version_pd.sort_values(by=['Component'], inplace=True, ignore_index=True)
        console = Console(record=True, color_system='truecolor', force_terminal=True)
        table = Table(
            box=ROUNDED,
            show_header=True,
            header_style="bold yellow",
            border_style="cyan",
            padding=(0, 1),
            row_styles=["", "dim"],
            expand=False,
        )
        table.add_column("Component", style="bold cyan", no_wrap=True, min_width=18)
        table.add_column("Version",   style="white",     max_width=60)
        for row in version_pd.itertuples(index=False):
            table.add_row(str(row[0]), str(row[1]))
        panel = Panel(
            table,
            title="[bold bright_blue] Odin Shell — Version Information [/]",
            subtitle=f"[dim]Shell Version: [cyan]{Constants.SHELL_VERSION}[/cyan][/dim]",
            border_style="bright_blue",
            padding=(1, 2),
        )
        with console.capture() as capture:
            console.print(panel)
        self.ppaged(capture.get())


    def help_version(self) -> None:
        """Display help information for the version command."""
        print(f"""
        [yellow]Usage[/]:
            version

        [blue]Description[/]:
            Displays the version information for the Odin Shell and its components.
            This includes the shell version and the versions of all loaded libraries.

        [magenta]Examples[/]:
    
            ([blue]Odin Shell[/]) : version

              Odin Shell Version : {Constants.SHELL_VERSION}
              
              Odin Library Versions
            ┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
            ┃ [yellow]Component[/]    ┃ [green]Version[/]                              ┃
            ┣━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
            ┃ fingerprints ┃ 20250918-05d3b9f5                    ┃
            ┃ framework    ┃ st-framework-3.1.0-20250918_05d3b9f5 ┃
            ┃ preupgrade   ┃ 20250918-05d3b9f5                    ┃
            ┃ server       ┃ 20250918-05d3b9f5                    ┃
            ┃ signature    ┃ 20250918-05d3b9f5                    ┃
            ┃ utilities    ┃ 20250918-05d3b9f5                    ┃
            ┗━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
            """)


    def do_release_notes(self,line:str) -> None:
        """Display the release notes.

        Args:
            line (str): The command line input.
        """
        try:
            with open(Constants.RELEASE_NOTES, "r", encoding="utf-8") as f:
                markdown_content = f.read()
            md = Markdown(markdown_content, justify="left")
            console = Console(record=True, color_system="truecolor", force_terminal=True)
            with console.capture() as capture:
                console.print(md)
                console.print("\n")
            self.ppaged(capture.get())
        except Exception as e:
            print(f"\n[red]Error reading release notes[/] : {e}\n")


    def help_release_notes(self) -> None:
        """Display help information for the release_notes command."""
        print("""
        [yellow]Usage[/]:
            release_notes

        [blue]Description[/]:
            Displays the Odin Shell release notes in a scrollable pager.
            The notes are rendered from [cyan]release_notes.md[/] bundled with the shell
            and include a full per-version change log.

        [magenta]Notes[/]:
            • Navigate with arrow keys or [yellow]Page Up[/] / [yellow]Page Down[/].
            • Press [yellow]q[/] to exit the pager.
            • Press [yellow]/[/] to search within the notes.

        [magenta]Examples[/]:

            ([blue]Odin Shell[/]) : release_notes

            # Odin Shell Release Notes

            ## Version 1.1.0 — February 26, 2026

            Major reliability, security, and quality-of-life overhaul …
        """)


    # ───────────────────────────────────────────────────── manual ───

    def do_manual(self, line: str) -> None:
        """Browse the Odin Shell documentation.

        With no argument shows the topic index.  With a topic name pages through that
        section of the manual.

        Args:
            line (str): Optional topic name.
        """
        if line.strip() == 'help':
            self.help_manual()
            return
        topic = line.strip().lower()

        # ── No topic — show the index panel ───────────────────────────────────────
        if not topic:
            from rich.table import Table as _Table
            tbl = _Table.grid(padding=(0, 4))
            tbl.add_column(style="bold cyan",  min_width=14, no_wrap=True)
            tbl.add_column(style="dim white")
            for name, (_, desc) in Constants.MANUAL_TOPICS.items():
                tbl.add_row(name, desc)
            panel = Panel(
                Group(
                    Text(""),
                    Text("  Type  manual <topic>  to read a section.", style="dim"),
                    Text("  Press  q  or  Ctrl-C  to exit any paged view.", style="dim"),
                    Text(""),
                    tbl,
                    Text(""),
                ),
                title="[bold cyan]Odin Shell Manual[/bold cyan]",
                subtitle="[dim]manual <topic>  •  Tab-complete topic names[/dim]",
                border_style="cyan",
                expand=False,
            )
            self.console.print()
            self.console.print(panel)
            self.console.print()
            return

        # ── Topic — render the markdown and page it ─────────────────────────────────
        if topic not in Constants.MANUAL_TOPICS:
            close = [t for t in Constants.MANUAL_TOPICS if t.startswith(topic[:3])]
            self._run_validation_error(
                message=f"Unknown topic [bold yellow]{topic}[/bold yellow].",
                suggestions=close,
                suggestion_style="cyan",
                available=list(Constants.MANUAL_TOPICS.keys()),
                available_label="Topics",
                available_style="cyan",
            )
            return

        filename, _ = Constants.MANUAL_TOPICS[topic]
        md_path = Constants.MANUAL_DIR / filename
        try:
            with open(md_path, 'r', encoding='utf-8') as fh:
                content = fh.read()
        except (FileNotFoundError, OSError) as exc:
            self.console.print(f"\n[red]Error reading manual page[/] : {exc}\n")
            return

        md = Markdown(content, justify="left")
        record_console = Console(record=True, color_system="truecolor", force_terminal=True)
        with record_console.capture() as capture:
            record_console.print(md)
            record_console.print("\n")
        self.ppaged(capture.get())


    def complete_manual(self, text, line, begidx, endidx) -> list[str]:
        """Tab-complete manual topic names."""
        topics = list(Constants.MANUAL_TOPICS.keys())
        if text:
            return [t for t in topics if t.startswith(text)]
        return topics


    def help_manual(self) -> None:
        """Display help information for the manual command."""
        print("""
        [yellow]Usage[/]:
            manual
            manual <topic>

        [blue]Description[/]:
            Display the Odin Shell documentation.

            With no argument shows the topic index.  With a topic name pages through
            the documentation section for that topic.

            Navigation inside a paged section follows the standard [cyan]less[/] key bindings:
            [yellow]Space[/] / [yellow]Page Down[/]  — next page
            [yellow]b[/] / [yellow]Page Up[/]       — previous page
            [yellow]/pattern[/]         — search
            [yellow]q[/] or [yellow]Ctrl-C[/]        — exit back to shell

        [magenta]Available Topics[/]:
""")
        for name, (_, desc) in Constants.MANUAL_TOPICS.items():
            print(f"            [cyan]{name:<14}[/] {desc}")
        print()


    def do_list(self,line:str) -> None | Exception | ValueError:
        """List available modules or utilities.

        Args:
            line (str): The command line input. Can be empty or contain a module name to list its utilities.
        
        Returns:
            None: On successful execution.
            Exception: If there is an error retrieving modules or utilities.
            ValueError: If no modules or utilities are found in the response.
        """
        parser = argparse.ArgumentParser(prog='list', add_help=False)
        parser.add_argument('module', nargs='?', default=None, type=str, help='Module name')
        parser.add_argument('utility', nargs='?', default=None, type=str, help='Utility name')
        print("")
        try:
            args = parser.parse_args(shlex.split(line))
        except SystemExit:
            return
        module = args.module
        # Future Functionality
        utility = args.utility

        modules = list(self.org_util.utilDataClass.modules.to_dict()['Module Name'].values())
        console = Console(record=True, color_system='truecolor', force_terminal=True)

        # ── list healthcheck ────────────────────────────────────────────────────────
        if module == 'healthcheck':
            all_hc = self.rest_infra.valid_health_modules or []
            from rich.columns import Columns
            explicit_set = set(self._EXPLICIT_ONLY_MODULES)
            standard = [m for m in sorted(all_hc) if m not in explicit_set]
            explicit  = [m for m in sorted(all_hc) if m in explicit_set]
            rows = []
            if standard:
                rows.append(Text('  Standard modules  (included in default run)', style='dim'))
                rows.append(Columns([f'[cyan]{m}[/cyan]' for m in standard], padding=(0, 2), expand=False))
            if explicit:
                rows.append(Text(''))
                rows.append(Text('  Explicit-only  (must be requested by name)', style='dim'))
                rows.append(Columns([f'[yellow]{m}[/yellow]' for m in explicit], padding=(0, 2), expand=False))
            rows.append(Text(''))
            panel = Panel(
                Group(*rows),
                title='[bold bright_blue] Health Check Modules [/]',
                subtitle=f'[dim]{len(all_hc)} modules  •  [cyan]run healthcheck[/cyan] or [cyan]run healthcheck <module,...>[/cyan][/dim]',
                border_style='bright_blue',
                padding=(1, 2),
            )
            self.console.print()
            self.console.print(panel)
            self.console.print()
            return

        if module:
            if module not in modules:
                print(f"\n[red]Error[/] : Module [yellow]{module}[/] not found\n")
                print(f"[yellow]Available Modules[/] : {', '.join(modules)}\n")
                return
            util_df = self.org_util.utilDataClass.module_util[module]
            table = Table(
                box=ROUNDED,
                show_header=True,
                header_style="bold yellow",
                border_style="cyan",
                padding=(0, 1),
                row_styles=["", "dim"],
                expand=True,
            )
            table.add_column("Utility Name", style="bold cyan", no_wrap=True, min_width=24)
            table.add_column("Description",  style="white",    ratio=1)
            for row in util_df[['Name', 'Description']].itertuples(index=False):
                table.add_row(str(row.Name), str(row.Description))
            panel = Panel(
                table,
                title=f"[bold bright_blue] {module.capitalize()} — Utilities [/]",
                subtitle=f"[dim]{len(util_df)} utilit{'y' if len(util_df) == 1 else 'ies'}  •  [cyan]run {module} <utility>[/cyan] to execute[/dim]",
                border_style="bright_blue",
                padding=(1, 2),
            )
            with console.capture() as capture:
                console.print(panel)
            self.ppaged(capture.get())
        else:
            modules_df = self.org_util.utilDataClass.modules
            table = Table(
                box=ROUNDED,
                show_header=True,
                header_style="bold yellow",
                border_style="cyan",
                padding=(0, 1),
                row_styles=["", "dim"],
                expand=True,
            )
            table.add_column("Module Name",  style="bold cyan", no_wrap=True, min_width=18)
            table.add_column("Description",  style="white",     ratio=1)
            for row in modules_df.itertuples(index=False):
                table.add_row(str(row[0]), str(row[1]))
            panel = Panel(
                table,
                title="[bold bright_blue] Odin Shell — Available Modules [/]",
                subtitle=f"[dim]{len(modules_df)} modules  •  [cyan]list <module>[/cyan] to view utilities[/dim]",
                border_style="bright_blue",
                padding=(1, 2),
            )
            with console.capture() as capture:
                console.print(panel)
            self.ppaged(capture.get())
    

    def complete_list(self, text, line, begidx, endidx):
        """Tab-complete list: includes module names and the special 'healthcheck' keyword.

        Args:
            text (str): Partial text being completed.
            line (str): Full command line.
            begidx (int): Start of incomplete text.
            endidx (int): End of incomplete text.

        Returns:
            list[str]: Matching completions.
        """
        candidates = self.all_complete(text, line) or []
        if 'healthcheck'.startswith(text):
            candidates = ['healthcheck'] + [c for c in candidates if c != 'healthcheck']
        return candidates


    def help_list(self) -> None:
        """Display help information for the list command."""
        print("""
        [yellow]Usage[/]:
            list
            list <module>
            list healthcheck

        [blue]Description[/]:
            Lists available modules and utilities, or lists health check modules.

            [cyan]list[/]              Show all available utility modules.
            [cyan]list <module>[/]     Show all utilities within a specific module.
            [cyan]list healthcheck[/]  Show all available health check modules.

        [magenta]Examples[/]:

            ([blue]Odin Shell[/]) : list
            ([blue]Odin Shell[/]) : list shellRunner
            ([blue]Odin Shell[/]) : list healthcheck
        """)


    def do_run(self,line) -> None | Exception | ValueError:
        """Run a specified utility from a module.

        Args:
            line (str): The command line input.

        Returns:
            None | Exception | ValueError: Description of the return value.
        """
        parser = argparse.ArgumentParser(prog='run')
        parser.add_argument('module', nargs='?', default=None, type=str, help='Module name')
        parser.add_argument('utility', nargs='?', default=None,type=str, help='Utility name')
        parser.add_argument('prompt', nargs='?', default=None, help='Optional prompt data')
        parser.add_argument('input', nargs='?', default=None, help='Optional input data')
        parser.add_argument('--input', type=str, default=None, help='Enable manual input data')
        parser.add_argument('--prompt', type=str, default=None, help='Enable manual prompt data')
        parser.add_argument('--all', action='store_true', help='Define to run on all nodes')
        parser.add_argument('--json', action='store_true', help='Enable JSON output')
        parser.add_argument('--timeout', type=int, default=Constants.TIMEOUT, help='Define timeout value in minutes, default is 6 minutes.  NOTE If a timeout is set per utility, this will be ignored')
        parser.add_argument('--no-timeout', action='store_true', help='Disable timeout')
        parser.add_argument('--debug', action='store_true', help='Enable debug mode')
        parser.add_argument('--xr', action='store_true', help='Set to use non blocking API call, return run id')
        try:
            args = parser.parse_args(shlex.split(line))
            args = vars(args)
        except SystemExit:
            # argparse throws SystemExit on error, handle gracefully in CLI
            return
        if args.get('xr', False):
            uri = self.rest_infra.valid_uri["exec_util_unblock"]
        else:
            uri = self.rest_infra.valid_uri["exec_util_block"]
        if args.get('debug', False):
            self.debug_mode = True
            print(f'\n DEBUG : Current Args {args}\nDEBUG : Current Class Vars : {vars(self)}')
        if args.get('help', False):
            self.help_run()
        quiet = args.get('quiet', False)
        #Collect Timeout
        timeout = args.get('timeout')
        #If disable is offered up, set timeout to 14500
        if args.get('no_timeout', False):
            timeout = 14500
        #if run help executed, will display detailed help output
        module_name = args.get('module')
        if module_name == "help":
            self.help_run()
        #Define Utility name
        util_name = args.get('utility')

        # ── run healthcheck [module,...] shortcut ──────────────────────────────────
        if module_name == 'healthcheck':
            # util_name may be a comma- or space-separated list of HC modules
            hc_line = ' '.join(re.split(r'[,\s]+', util_name)) if util_name else ''
            self._do_healthcheck(hc_line)
            return

        #Collect any input prompt
        in_prompt = args.get('prompt', None)
        #Collect any input data
        in_data = args.get('input', None)
        # Security: reject forbidden characters and banned commands in user-supplied inputs
        for field_name, field_value in [("module", module_name), ("utility", util_name)]:
            if field_value and any(c in field_value for c in Constants.FORBIDDEN_CHARS):
                print(f"\n[red]Error[/] : {field_name} contains forbidden characters\n")
                return
            if field_value and field_value.lower() in Constants.FORBIDDEN_CMD:
                print(f"\n[red]Error[/] : {field_name} [yellow]{field_value}[/] is a forbidden command\n")
                return
        for field_name, field_value in [("prompt", in_prompt), ("input", in_data)]:
            if field_value and any(c in field_value for c in Constants.FORBIDDEN_CHARS):
                print(f"\n[red]Error[/] : {field_name} contains forbidden characters\n")
                return
        # ── Validate module and utility against known values ─────────────────
        valid_modules = list(self.org_util.utilDataClass.modules.to_dict()['Module Name'].values())

        if not module_name:
            self._run_validation_error(
                message="No module specified.  [dim]Tip: [cyan]run healthcheck[/cyan] to run a health check.[/dim]",
                available=sorted(valid_modules),
                available_label="Available modules",
                available_style="cyan",
            )
            return

        if module_name not in valid_modules:
            close = [m for m in valid_modules if m.lower().startswith(module_name.lower()[:3])]
            self._run_validation_error(
                message=f"Unknown module [bold yellow]{module_name}[/bold yellow]",
                suggestions=close,
                suggestion_style="cyan",
                available=sorted(valid_modules),
                available_label="Available modules",
                available_style="cyan",
            )
            return

        valid_utils = self.org_util.utilDataClass.module_util[module_name]['Name'].tolist()

        if not util_name:
            self._run_validation_error(
                message=f"No utility specified for module [bold cyan]{module_name}[/bold cyan].",
                available=sorted(valid_utils),
                available_label=f"Utilities in [cyan]{module_name}[/cyan]",
                available_style="yellow",
            )
            return

        if util_name not in valid_utils:
            close = [u for u in valid_utils if u.lower().startswith(util_name.lower()[:4])]
            self._run_validation_error(
                message=f"Unknown utility [bold yellow]{util_name}[/bold yellow] in module [bold cyan]{module_name}[/bold cyan].",
                suggestions=close,
                suggestion_style="yellow",
                available=sorted(valid_utils),
                available_label=f"Utilities in [cyan]{module_name}[/cyan]",
                available_style="yellow",
            )
            return
        # ─────────────────────────────────────────────────────────────────────

        #Define if process is to run on all nodes, fully implemented for shellRunner, and some scripts
        all = args.get('all', False)
        #Get return data type from the utility definition
        outFormat = self.org_util.module_util.get(module_name, {}).get(util_name, {}).get('Format', 'json')
        outType = self.org_util.module_util.get(module_name, {}).get(util_name, {}).get('Type', 'json')
        dataIn = self.org_util.module_util.get(module_name, {}).get(util_name, {}).get('DataIn', 'none')
        auth_required = self.org_util.module_util.get(module_name, {}).get(util_name, {}).get('Auth', False)
        if auth_required:
            self.do_iris(None)
        if not in_prompt and dataIn != "":
            # Get current history length to track new entries
            hist_len = 0
            if readline:
                try:
                    hist_len = readline.get_current_history_length()
                except Exception:
                    hist_len = 0
            while True:
                prompt_data = input(f'\n{dataIn} : ')
                # If enum is present, check input values
                # Handle prompt input with required/default logic
                if prompt_data == '':
                    in_prompt = ""
                else:
                    in_prompt = prompt_data
                break
            # Remove any lines added to history during prompt input
            if readline:
                try:
                    new_hist_len = readline.get_current_history_length()
                    for _ in range(new_hist_len - hist_len):
                        readline.remove_history_item(hist_len)
                except Exception:
                    pass
        if outType == "dataframe|json":
            outType = "dataframe"
        if auth_required:
            payload:dict = self.rest_infra.build_payload(module = module_name,
                                                      util = util_name,
                                                      inPrompt = in_prompt,
                                                      inData = in_data,
                                                      token = str(self.iris.token),
                                                      allNodes = all,
                                                      timeout = timeout)
        else:
            payload:dict = self.rest_infra.build_payload(module = module_name,
                                                      util = util_name,
                                                      inPrompt = in_prompt,
                                                      inData = in_data,
                                                      allNodes = all,
                                                      timeout = timeout)
        border_style = Style(color="white", bold=True)
        progress = Progress(TextColumn("[progress.description]{task.description}"),
                            BarColumn(bar_width=None, style="#0057B7", pulse_style="#FFDD00"),
                            TimeElapsedColumn(),
                            refresh_per_second=20,
                            transient=True)
        progress.add_task(description="",total=None, start=True)
        panel = Panel(progress, title="Executing Utility", subtitle=f"[cyan]{module_name} {util_name}[/]",style=border_style)
        centered_panel = Align.center(panel)
        # Add blank lines after the panel
        blank_space = Text("")
        group = Group(blank_space,centered_panel, blank_space)
        with Live(group, refresh_per_second=20, transient=True):
            if not self.test:
                result:AsyncResult = self.pool.apply_async(self.rest_infra.sif_request, kwds={'method':'POST','uri':uri,'payload':payload,'timeout':timeout})
                out,err,code = result.get(timeout=Constants.TIMEOUT)
            else:
                time.sleep(5)
                with open(Constants.SHELL_RUNNER_RESULTS, "r", encoding="utf-8") as f:
                    out = json.load(f)
                err = None
                code = 200
            progress.stop()
        if code != 200:
            print(f"\n[red]Error executing command[/] : {err}\n")
            return
        print()
        if not args.get('xr', False):
            self.cli_print.print_output(data=out, dataType=outType, dataFormat=outFormat)
        else:
            print(f"[green]Run ID[/] : [yellow]{out.get('hcUtilId')}[/]\n")
            self.xr_runs[out.get('hcUtilId')] = f"[green]{module_name}[/] [yellow]{util_name}[/] [blue]{in_prompt if in_prompt else ''}[/] [magenta]{in_data if in_data else ''}[/]\n\n[yellow] Optional Args[/]\n    [green]all[/]        : {all}\n    [green]json[/]       : {args.get('json', False)}\n    [green]timeout[/]    : {timeout}\n    [green]no-timeout[/] : {args.get('no_timeout', False)}"
        return

    
    def complete_run(self, text, line, begidx, endidx) -> list[str]:
        """Tab-complete the run command.

        Handles both  run <module> <utility>  and  run healthcheck [module,...].

        Args:
            text (str): Partial text being completed.
            line (str): Full command line.
            begidx (int): Start of incomplete text.
            endidx (int): End of incomplete text.

        Returns:
            list[str]: Matching completions.
        """
        parts = line.split()
        # Position 1 — completing the module/keyword
        if len(parts) == 1 or (len(parts) == 2 and not line.endswith(' ')):
            candidates = self.all_complete(text, line) or []
            if 'healthcheck'.startswith(text):
                candidates = ['healthcheck'] + [c for c in candidates if c != 'healthcheck']
            return candidates
        # Position 2 with 'healthcheck' — offer HC module names
        if len(parts) >= 2 and parts[1] == 'healthcheck':
            all_hc = self.rest_infra.valid_health_modules or []
            already = set(parts[2:])
            candidates = [m for m in all_hc if m not in already]
            if text:
                return [m for m in candidates if m.startswith(text)]
            return candidates
        # Default — delegate to all_complete for module utilities
        return self.all_complete(text, line)


    def help_run(self) -> None:
        """Display help information for the run command."""
        print("""
        [yellow]Usage[/]:
            run <module> <utility> [options]
            run healthcheck [module,...]

        [blue]Description[/]:
            Executes a utility from a given module, or runs a health check when the
            special module [cyan]healthcheck[/cyan] is given.

            Utility options
            ─────────────────────────────────────────────────────
            --all          Run on all nodes
            --json         Enable JSON output
            --timeout N    Timeout in minutes (default 6)
            --no-timeout   Disable timeout
            --xr           Non-blocking async run (returns a run ID)
            --prompt TEXT  Optional prompt input
            --input  TEXT  Optional input data

        [magenta]Examples[/]:

            ([blue]Odin Shell[/]) : run shellRunner getClusterInfo --json

            ([blue]Odin Shell[/]) : run healthcheck
            ([blue]Odin Shell[/]) : run healthcheck disk,network
            ([blue]Odin Shell[/]) : run healthcheck fingerprint
        """)

    def _run_validation_error(
        self,
        message: str,
        available: list,
        available_label: str,
        available_style: str,
        suggestions: list = None,
        suggestion_style: str = "yellow",
    ) -> None:
        """Display a rich Panel error box for invalid run command arguments."""
        from rich.columns import Columns

        body_parts: list = [Text(""), Text.from_markup(f"  {message}")]

        if suggestions:
            body_parts.append(Text(""))
            body_parts.append(Text("  Did you mean?", style="dim italic"))
            rendered = [f"[{suggestion_style}]{s}[/{suggestion_style}]" for s in suggestions]
            body_parts.append(Columns(rendered, padding=(0, 2), expand=False))

        body_parts.append(Text(""))
        body_parts.append(Text.from_markup(f"  [dim]{available_label}:[/dim]"))
        rendered_avail = [f"[{available_style}]{a}[/{available_style}]" for a in available]
        body_parts.append(Columns(rendered_avail, padding=(0, 2), expand=False))
        body_parts.append(Text(""))

        panel = Panel(
            Group(*body_parts),
            title="[red]Command Error[/red]",
            border_style="red",
            expand=False,
            padding=(0, 2),
        )
        self.console.print()
        self.console.print(panel)
        self.console.print()

    # Modules that must be explicitly requested — never run in the default sweep.
    _EXPLICIT_ONLY_MODULES: list[str] = ['fingerprint', 'preUpgrade', 'patch']

    # ──────────────────────────────────────────────────────────────────────

    def do_get(self, line) -> None:
        """Retrieve run results or history.

        Subcommands:
            get healthcheck runs                   List all health check run IDs and dates.
            get healthcheck <run_id>               Show detailed results for a health check run.
            get healthcheck <run_id> --module <m>  Filter results to one module.
            get utility runs                       List all utility run results.
            get utility <run_id>                   Print the output of a specific utility run.
            get utility status                     Show live status for all async utility runs.
            get utility status <run_id>            Show live status for a specific async run.

        Args:
            line (str): Subcommand string.
        """
        if not line or line.strip() == 'help':
            self.help_get()
            return
        parts = shlex.split(line)
        if len(parts) < 2:
            self.help_get()
            return
        category = parts[0].lower()
        rest     = parts[1:]
        arg      = rest[0].lower() if rest else ''
        extra    = ' '.join(rest[1:])

        if category == 'healthcheck':
            if not arg or arg == 'runs':
                self._get_hc_runs()
            else:
                # arg is a run_id; pass optional --module flag via extra
                run_id_line = arg + (' ' + extra if extra else '')
                self._get_hc_result(run_id_line)
        elif category == 'utility':
            if not arg or arg == 'runs':
                self._list_results()
            elif arg == 'status':
                self._get_util_status(extra.strip() if extra else '')
            else:
                self._get_result(arg)
        else:
            self.console.print()
            self.console.print(
                f"[red]Unknown category[/] [bold yellow]{category}[/bold yellow].  "
                "Use [cyan]healthcheck[/cyan] or [cyan]utility[/cyan]."
            )
            self.console.print()


    def complete_get(self, text, line, begidx, endidx) -> list[str]:
        """Tab-complete the get command."""
        parts = shlex.split(line) if line.strip() else []
        n     = len(parts)
        # First token: category
        if n <= 1 or (n == 2 and not line.endswith(' ')):
            cats = ['healthcheck', 'utility']
            return [c for c in cats if c.startswith(text)]
        category = parts[1].lower() if len(parts) > 1 else ''
        # Second token: 'runs', 'status', or a run_id
        if category in ('healthcheck', 'utility') and (n == 2 or (n == 3 and not line.endswith(' '))):
            subs = ['runs'] + (['status'] if category == 'utility' else [])
            uri_key = 'list_health_check_runs' if category == 'healthcheck' else 'list_util_runs'
            try:
                cache_ts, cached = self._result_cache
                if time.time() - cache_ts > 30:
                    fresh, _, code = self.rest_infra.sif_request(
                        method='GET', uri=self.rest_infra.valid_uri[uri_key], timeout=10
                    )
                    if code == 200 and isinstance(fresh, list):
                        cached = [str(r) for r in fresh]
                        self._result_cache = (time.time(), cached)
                subs += [r for r in cached if r not in subs]
            except Exception:
                pass
            return [s for s in subs if s.startswith(text)]
        # Third token after 'utility status': complete with run IDs from XR status
        if category == 'utility' and len(parts) > 2 and parts[2].lower() == 'status':
            if n == 3 or (n == 4 and not line.endswith(' ')):
                try:
                    fresh, _, code = self.rest_infra.sif_request(
                        method='GET',
                        uri=self.rest_infra.valid_uri['get_util_xr_status'],
                        timeout=10,
                    )
                    if code == 200:
                        if isinstance(fresh, list):
                            ids = [str(e.get('utilId', e.get('hcUtilId', e.get('runId', '')))) for e in fresh if isinstance(e, dict)]
                        elif isinstance(fresh, dict):
                            ids = [str(k) for k in fresh]
                        else:
                            ids = []
                        return [i for i in ids if i.startswith(text)]
                except Exception:
                    pass
        return []


    def help_get(self) -> None:
        """Display help for the get command."""
        print("""
        [yellow]Usage[/]:
            get healthcheck runs
            get healthcheck <run_id> [--module <module>]
            get utility runs
            get utility status
            get utility status <run_id>
            get utility <run_id>

        [blue]Description[/]:
            Retrieve run history and results for health checks and utility runs.

            [cyan]get healthcheck runs[/]              Lists all recorded health check runs with IDs and dates.
            [cyan]get healthcheck <run_id>[/]           Displays detailed results for a specific health check.
            [cyan]get healthcheck <run_id> --module[/]  Filters results to a single module.
            [cyan]get utility runs[/]                   Lists all utility run results by module and utility name.
            [cyan]get utility status[/]                 Shows live status for all async (--xr) utility runs.
            [cyan]get utility status <run_id>[/]        Shows live status for a specific async run.
            [cyan]get utility <run_id>[/]               Prints the output of a specific utility run.

        [magenta]Examples[/]:

            ([blue]Odin Shell[/]) : get healthcheck runs
            ([blue]Odin Shell[/]) : get healthcheck 1758813534677587771
            ([blue]Odin Shell[/]) : get healthcheck 1758813534677587771 --module software
            ([blue]Odin Shell[/]) : get utility runs
            ([blue]Odin Shell[/]) : get utility status
            ([blue]Odin Shell[/]) : get utility status 1758554741012142432
            ([blue]Odin Shell[/]) : get utility 1758554741012142432
        """)


    def _do_healthcheck(self, line) -> None:
        """Run a health check on the system.

        Args:
            line (str): The command line input.  Optionally pass one or more
                module names to run only those modules (including explicit-only
                ones such as ``fingerprint`` or ``preUpgrade``).
        """
        if line == 'help':
            self._help_healthcheck()
            return

        console = Console(color_system="truecolor", force_terminal=True)

        # ── Step 1: collect available modules ────────────────────────────────
        with Progress(
            SpinnerColumn(spinner_name="dots"),
            TextColumn("[cyan]{task.description}[/cyan]"),
            transient=True,
            console=console,
        ) as _p:
            _p.add_task("Collecting available health check modules…", total=None)
            all_modules = self.rest_infra.valid_health_modules or []

        stLogger.debug(f"do_healthcheck: valid_health_modules = {all_modules!r}")

        if not all_modules:
            print("[red]Error[/] : Unable to retrieve health check modules from the API.\n")
            return

        # ── Step 2: resolve which modules to run ─────────────────────────────
        requested = [m.strip() for m in shlex.split(line) if m.strip()]
        if requested:
            # Validate every requested name
            invalid = [m for m in requested if m not in all_modules]
            if invalid:
                inv_str = "  ".join(f"[red]{m}[/red]" for m in invalid)
                avail_str = "  ".join(f"[cyan]{m}[/cyan]" for m in sorted(all_modules))
                console.print(f"\n[red]Unknown module(s)[/] : {inv_str}")
                console.print(f"[dim]Available[/dim]  →  {avail_str}\n")
                return
            modules = requested
        else:
            # Default run — exclude explicit-only modules
            modules = [m for m in all_modules if m not in self._EXPLICIT_ONLY_MODULES]

        mod_list = "  ".join(f"[cyan]{m}[/cyan]" for m in sorted(modules))
        console.print(f"\n[dim]Modules[/dim]  →  {mod_list}\n")

        # ── Step 3: POST to start the run ─────────────────────────────────────
        uri     = self.rest_infra.valid_uri["exec_healthcheck"]
        payload = {"status": "start", "modules": modules}

        with Progress(
            SpinnerColumn(spinner_name="dots"),
            TextColumn("[cyan]{task.description}[/cyan]"),
            transient=True,
            console=console,
        ) as _p:
            _p.add_task("Starting health check…", total=None)
            results, error, code = self.rest_infra.sif_request(
                method='POST', payload=payload, uri=uri, timeout=300
            )

        if code == 409:
            print(f"[red]Health Check already running[/]\n")
            return
        if code != 200 or error:
            print(results, error, code)
            print(f"[red]Error running health check[/] : {error}\n")
            return

        run_id = str(results.get('hcRunId', ''))
        console.print(f"[green]✔  Health Check started[/]  [dim]·[/dim]  [yellow]Run ID[/] : [bold]{run_id}[/bold]\n")

        # ── Step 4: live progress TUI (has its own init spinner) ──────────────
        start_time = datetime.now()
        self.show_module_progress(modules=modules, start_time=start_time, run_id=run_id)

        print("")

    # ── Healthcheck TUI helpers (tui.py style) ────────────────────────────────

    def _hc_counts_text(self, counts: dict | None) -> str:
        """Fixed-width Rich markup for a module's P/W/F/S result counters."""
        if not counts:
            return "[dim]P:  — W:  — F:  — S:  —[/dim]"
        p, w, f, s = counts.get("pass", 0), counts.get("warn", 0), counts.get("fail", 0), counts.get("skip", 0)
        p_str = f"[green]P:{p:>3}[/green]"
        w_str = f"[yellow]W:{w:>3}[/yellow]" if w else f"[dim]W:{w:>3}[/dim]"
        f_str = f"[red]F:{f:>3}[/red]"       if f else f"[dim]F:{f:>3}[/dim]"
        s_str = f"[blue]S:{s:>3}[/blue]"     if s else f"[dim]S:{s:>3}[/dim]"
        return f"{p_str} {w_str} {f_str} {s_str}"

    def _fetch_hc_results(self, run_id: str) -> tuple[dict, list]:
        """Poll /master/result/{run_id} (or /current as fallback) and return (module_counters, failures)."""
        _PASS, _FAIL, _WARN, _SKIP = 0, 1, 4, 3
        module_counters: dict = {}
        failures: list = []
        try:
            # Prefer the run-specific endpoint so results for finished modules
            # are not lost when /current only reflects the active run window.
            if run_id:
                uri = self.rest_infra.valid_uri["get_runid_healthcheck_results"].replace("RUNID", run_id)
            else:
                uri = self.rest_infra.valid_uri["get_current_healthcheck_results"]
            data, _, code = self.rest_infra.sif_request(
                method="GET",
                uri=uri,
                timeout=10,
            )
            stLogger.debug(f"_fetch_hc_results uri={uri} code={code} type={type(data).__name__}")
            if code != 200 or not isinstance(data, dict):
                stLogger.warning(f"_fetch_hc_results: unexpected response code={code} data={data!r}")
                return module_counters, failures
            results = data.get("results", [])
            stLogger.debug(f"_fetch_hc_results: {len(results)} result entries")
            if results:
                stLogger.debug(f"_fetch_hc_results: sample keys = {list(results[0].keys()) if results else []}")
            for r in results:
                mod  = r.get("module", "unknown")
                cv   = r.get("code", -1)
                if mod not in module_counters:
                    module_counters[mod] = {"pass": 0, "fail": 0, "warn": 0, "skip": 0}
                if cv == _PASS:
                    module_counters[mod]["pass"] += 1
                elif cv == _FAIL:
                    module_counters[mod]["fail"] += 1
                    failures.append(r)
                elif cv == _WARN:
                    module_counters[mod]["warn"] += 1
                    failures.append(r)
                elif cv == _SKIP:
                    module_counters[mod]["skip"] += 1
        except Exception as e:
            stLogger.error(f"_fetch_hc_results exception: {e}", exc_info=True)
        return module_counters, failures

    def _build_hc_renderable(
        self,
        modules: list[str],
        finished: list[str],
        running: bool,
        counters: dict,
        elapsed,
        run_id: str,
        footer: tuple,
        start_time: datetime | None = None,
        progress: "Progress | None" = None,
        task_ids: "dict | None" = None,
    ) -> Group:
        """Build the tui.py-style Live renderable for the healthcheck display."""
        now_str = datetime.now().strftime("%H:%M:%S")
        secs    = int(elapsed.total_seconds())
        m, s    = divmod(secs, 60)
        elapsed_str = f"{m:02d}:{s:02d}" if m else f"{s}s"

        title = Rule(
            f"[bold cyan]Odin Diagnostics[/bold cyan]  [dim]·[/dim]  "
            f"[dim]Run [yellow]{run_id}[/yellow][/dim]",
            style="cyan",
        )
        _start_str = start_time.strftime("%H:%M:%S") if start_time else "—"
        timing = Rule(
            f"[dim]started [white]{_start_str}[/white]  ·  now [white]{now_str}[/white]  ·  elapsed [white]{elapsed_str}[/white][/dim]",
            style="dim cyan",
        )

        # Reuse the caller-supplied Progress object so spinner/bar state persists
        # across frames.  On first call (progress is None) we create and populate it;
        # on subsequent calls we update existing task fields in-place.
        if progress is None or task_ids is None:
            raise ValueError("progress and task_ids must be provided")

        for module in modules:
            counts_str = self._hc_counts_text(counters.get(module))
            tid = task_ids[module]
            if module in finished:
                progress.update(tid, completed=100, total=100,
                                state="[bright_green]done[/bright_green]", counts=counts_str)
            elif not running:
                progress.update(tid, completed=0, total=100,
                                state="[dim]waiting[/dim]", counts=counts_str)
            else:
                progress.update(tid, completed=0, total=None,
                                state="[yellow]running[/yellow]", counts=counts_str)

        total_pass = sum(v.get("pass", 0) for v in counters.values())
        total_warn = sum(v.get("warn", 0) for v in counters.values())
        total_fail = sum(v.get("fail", 0) for v in counters.values())
        total_skip = sum(v.get("skip", 0) for v in counters.values())

        totals = Table.grid(padding=(0, 2))
        totals.add_column(style="bold white", justify="right", min_width=8)
        totals.add_column()
        totals.add_row(
            "Totals",
            f"[green]Pass:{total_pass:>3}[/green]  "
            f"[yellow]Warn:{total_warn:>3}[/yellow]  "
            f"[red]Fail:{total_fail:>3}[/red]  "
            f"[blue]Skip:{total_skip:>3}[/blue]",
        )

        footer_style, footer_label = footer
        return Group(
            Text(""), title, Text(""), timing,
            progress,
            Rule(style="dim cyan"), Text(""),
            totals,
            Text(footer_label, style=footer_style),
            Text(""),
        )

    def _print_hc_report(self, failures: list, run_id: str = "") -> None:
        """Print a post-run failure/warning summary grouped by module."""
        _FAIL, _WARN = 1, 4
        from rich import box as _box
        fail_list = [f for f in failures if f.get("code") == _FAIL]
        warn_list = [f for f in failures if f.get("code") == _WARN]
        console = Console(color_system="truecolor", force_terminal=True)
        run_suffix = f"  [dim]·[/dim]  [dim]Run [yellow]{run_id}[/yellow][/dim]" if run_id else ""
        console.print()
        console.print(Rule(f"[bold white]Run Report[/bold white]{run_suffix}", style="dim cyan"))
        if not fail_list and not warn_list:
            console.print("[bright_green]  ✓ All tests passed — no failures or warnings.[/bright_green]")
            console.print()
            return

        def _section(entries: list, label: str, hdr_style: str, col_style: str) -> None:
            seen: dict = {}
            for e in entries:
                out_msg = e.get("out", "") or ""
                key = (e.get("module", ""), str(e.get("testNumber", "")), e.get("test", ""), out_msg)
                if key not in seen:
                    seen[key] = {
                        "module":      e.get("module", ""),
                        "test_number": str(e.get("testNumber", "")),
                        "out":         out_msg,
                        "nodes":       set(),
                    }
                nd = e.get("nodeData") or {}
                seen[key]["nodes"].add(nd.get("nodeIp", "unknown"))
            deduped = sorted(seen.values(), key=lambda x: (x["module"], x["test_number"]))
            total_nodes_hit = sum(len(g["nodes"]) for g in deduped)
            console.print(
                f"\n[{hdr_style}]  {label} — "
                f"{len(entries)} result(s)  ·  {len(deduped)} unique test(s)  ·  "
                f"{total_nodes_hit} node/test instance(s)[/{hdr_style}]"
            )
            for mod in sorted({g["module"] for g in deduped}):
                mod_rows = [g for g in deduped if g["module"] == mod]
                console.print(Rule(
                    f"[cyan]{mod}[/cyan]  [dim]({len(mod_rows)} test(s))[/dim]",
                    style="dim cyan",
                ))
                tbl = Table(
                    show_header=True, header_style=f"bold {col_style}",
                    box=_box.SIMPLE_HEAVY, expand=True, show_lines=True, padding=(0, 1),
                )
                tbl.add_column("Test ID",   style="dim",     no_wrap=True)
                tbl.add_column("Output",                     overflow="fold", ratio=3)
                tbl.add_column("Nodes",     style=col_style, overflow="fold", ratio=2)
                for g in mod_rows:
                    tbl.add_row(
                        g["test_number"] or "—",
                        g["out"]         or "—",
                        ", ".join(sorted(g["nodes"])),
                    )
                console.print(tbl)

        if fail_list:
            _section(fail_list, "Failures", "red",    "red")
        if warn_list:
            _section(warn_list, "Warnings", "yellow", "yellow")
        console.print(
            "[dim]  → To view the full report run: [cyan]get utility runs[/cyan][/dim]"
        )
        console.print()

    # ── Main healthcheck progress loop ────────────────────────────────────────

    def show_module_progress(
        self,
        modules: list[str] = [],
        start_time: datetime | None = None,
        run_id: str = "",
        poll_interval: float = 0.5,
    ) -> None:
        """Live animated TUI — style matched to tui.py / Odin Diagnostics."""
        _COOLDOWN_SECS = 10.0
        _F_FINISHED    = ("bright_green", "  ✓  Finished")
        _F_RUNNING     = ("yellow",       "  ●  Running")
        _F_WAITING     = ("dim",          "  ○  Waiting…")

        if start_time is None:
            start_time = datetime.now()
        modules = sorted(modules)

        console = Console(color_system="truecolor", force_terminal=True)

        # Wait for first valid status response before entering the Live display.
        # Show a spinner so the user knows work is happening during node init.
        with Progress(
            SpinnerColumn(spinner_name="dots"),
            TextColumn("[cyan]{task.description}[/cyan]"),
            transient=True,
            console=console,
        ) as _init_progress:
            _init_progress.add_task("Waiting for nodes to initialize…", total=None)
            while True:
                status_data = self.get_status()
                if not status_data:
                    time.sleep(0.5)
                    continue
                if "nodes" not in status_data or not status_data["nodes"]:
                    time.sleep(0.5)
                    continue
                break
        progress = Progress(
            TextColumn("[cyan]{task.description:<22}[/cyan]", justify="left"),
            SpinnerColumn(spinner_name="dots", finished_text="[bright_green]✔[/bright_green]"),
            BarColumn(
                bar_width=25,
                style="dim blue",
                complete_style="bright_green",
                finished_style="bright_green",
                pulse_style="yellow",
            ),
            TextColumn("{task.fields[state]:<12}", justify="left"),
            TextColumn("{task.fields[counts]}", justify="left",
                       table_column=Column(min_width=26)),
            expand=False,
        )
        task_ids: dict = {
            mod: progress.add_task(mod, total=100, completed=0,
                                   state="[dim]waiting[/dim]",
                                   counts=self._hc_counts_text(None))
            for mod in modules
        }

        in_cooldown:   bool  = False
        last_finish_t: float = 0.0
        finished:      list  = []
        running:       bool  = False
        failures:      list  = []
        final_renderable     = None

        def _footer() -> tuple:
            if in_cooldown:
                return ("cyan", "  ⟳  Collecting data…")
            if running:
                return _F_RUNNING
            return _F_WAITING

        try:
            with Live(Text(""), console=console, refresh_per_second=20, screen=True) as live:
                while True:
                    # Poll /master/status and derive per-module status map.
                    # masterStatus.nodes[].modules[].{name, status}
                    # A module is "Finished" only when every node that reports
                    # it shows status "Finished".
                    status_data = self.get_status() or {}
                    module_all_statuses: dict[str, list[str]] = {}
                    for node in status_data.get("nodes", []):
                        for mod_entry in node.get("modules", []):
                            mod_name   = mod_entry.get("name", "")
                            mod_status = mod_entry.get("status", "")
                            if mod_name:
                                module_all_statuses.setdefault(mod_name, []).append(mod_status)
                    status_map = {
                        m: (
                            "Finished"
                            if module_all_statuses.get(m)
                            and all(s == "Finished" for s in module_all_statuses[m])
                            else (module_all_statuses.get(m) or [""])[0]
                        )
                        for m in modules
                    }

                    counters, failures = self._fetch_hc_results(run_id)
                    finished = [m for m in modules if status_map.get(m) == "Finished"]
                    running  = any(
                        status_map.get(m) in ("Initializing", "Running", "Start")
                        for m in modules
                    )

                    # Enter cooldown once all modules report Finished.
                    if (not in_cooldown and modules
                            and all(status_map.get(m) == "Finished" for m in modules)):
                        in_cooldown   = True
                        last_finish_t = time.time()

                    if in_cooldown and (time.time() - last_finish_t) >= _COOLDOWN_SECS:
                        break

                    elapsed          = datetime.now() - start_time
                    final_renderable = self._build_hc_renderable(
                        modules, finished, running, counters, elapsed, run_id, _footer(),
                        start_time=start_time, progress=progress, task_ids=task_ids,
                    )
                    live.update(final_renderable)
                    time.sleep(poll_interval)

                # Final fetch + render before exiting Live.
                counters, failures = self._fetch_hc_results(run_id)
                elapsed          = datetime.now() - start_time
                final_renderable = self._build_hc_renderable(
                    modules, finished, running, counters, elapsed, run_id, _F_FINISHED,
                    start_time=start_time, progress=progress, task_ids=task_ids,
                )
                live.update(final_renderable)
                time.sleep(0.5)

            # Print the frozen final TUI frame to the primary (scrollback) buffer.
            if final_renderable is not None:
                console.print(final_renderable)

        except KeyboardInterrupt:
            pass

        self._print_hc_report(failures, run_id=run_id)

    def _complete_healthcheck(self, text, line, begidx, endidx) -> list[str]:
        """Tab-complete module names for the healthcheck command."""
        all_modules = self.rest_infra.valid_health_modules or []
        already = set(shlex.split(line)[1:])  # modules already on the line
        candidates = [m for m in all_modules if m not in already]
        if text:
            return [m for m in candidates if m.startswith(text)]
        return candidates

    def _help_healthcheck(self) -> None:
        """Display help information for the run_healthcheck command."""
        explicit = "  ".join(f"[yellow]{m}[/yellow]" for m in secureDebug._EXPLICIT_ONLY_MODULES)
        print(f"""
        [yellow]Usage[/]:
            healthcheck [module ...]

        [blue]Description[/]:
            Runs a health check on the system and displays the results.

            With no arguments, all standard modules are run automatically.
            The following modules are [bold]excluded[/bold] from the default run
            and must be requested explicitly:

              {explicit}

            To run explicit-only or a custom subset, pass the module name(s):

              healthcheck fingerprint
              healthcheck fingerprint preUpgrade

        [magenta]Examples[/]:
            (Odin Shell) : healthcheck

            ✔  Health Check started  ·  Run ID : 1758821942696767388

            ──────────────── Odin Diagnostics  ·  Run 1758821942696767388 ────────────────
            ─────────────── now 10:32:57  ·  elapsed 00:04 ──────────────────────────────
            disk                  ✔ ██████████████████████████ done         P: 14 W:  0 F:  0 S:  2
            network               ✔ ██████████████████████████ done         P:  8 W:  1 F:  0 S:  0
            software              ⠿ ██████████████████████████ running      P:  6 W:  0 F:  0 S:  0
            ─────────────────────────────────────────────────────────────────────────────
            Totals    Pass: 28  Warn:  1  Fail:  0  Skip:  2
            ●  Running

            ─────────────────────────── Health Check Report ─────────────────────────────

              Warnings — 1 result(s)  ·  1 unique test(s)
            ──────────────── network  (1 test(s)) ──────────────────────────────────────
             Test ID   Description                    Nodes
            ─────────────────────────────────────────────────────────────────────────────
             1234      DNS resolution degraded         10.14.7.36
                    
        """)

    def _get_hc_runs(self, line='') -> None:
        """Retrieve and display past health check runs.

        Args:
            line (str): The command line input.
        """
        if line == 'help':
            self._help_get_hc_runs()
            return
        print('')
        uri = self.rest_infra.valid_uri["list_health_check_runs"]
        results, error, code = self.rest_infra.sif_request(method='GET', uri=uri, timeout=30)
        if code != 200 or error:
            print(f"\n[red]Error retrieving health check runs[/] : {error}\n")
            return
        console = Console(record=True, color_system='truecolor', force_terminal=True)
        table = Table(
            box=ROUNDED,
            show_header=True,
            header_style="bold yellow",
            border_style="cyan",
            padding=(0, 1),
            row_styles=["", "dim"],
            expand=False,
        )
        table.add_column("Run ID",   style="bold cyan", no_wrap=True, min_width=22)
        table.add_column("Run Date", style="white",     min_width=20)
        for run_id_str in results:
            try:
                run_id = int(run_id_str)
                run_dt = datetime.fromtimestamp(run_id / 1_000_000_000)
                run_dt_str = run_dt.strftime("%Y-%m-%d %H:%M:%S")
            except Exception:
                run_dt_str = "[red]Invalid[/]"
            table.add_row(str(run_id_str), run_dt_str)
        panel = Panel(
            table,
            title="[bold bright_blue] Health Check Runs [/]",
            subtitle=f"[dim]{len(results)} run(s)  •  [cyan]get_healthcheck_result <run_id>[/cyan] to view[/dim]",
            border_style="bright_blue",
            padding=(1, 2),
        )
        with console.capture() as capture:
            console.print(panel)
        self.ppaged(capture.get())

    def _help_get_hc_runs(self) -> None:
        """Display help information for the get_healthcheck_runs command."""
        print("""
        [yellow]Usage[/]:
            get_healthcheck_runs

        [blue]Description[/]:
            Retrieves and displays past health check runs.

        [magenta]Examples[/]:
    
            ([blue]Odin Shell[/]) : get_healthcheck_runs 

            ┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
            ┃       [bold magenta]Run ID[/]        ┃        [bold magenta]Date[/]         ┃
            ┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
            │ [yellow]1758813534677587771[/] │ [green]2025-09-25 08:18:54[/] │
            └─────────────────────┴─────────────────────┘
        """)

    def _get_hc_result(self, line='') -> None:
        """Retrieve and display the result of a specific health check run by its run ID.

        Args:
            line (str): The command line input containing the run ID.
        """
        parser = argparse.ArgumentParser(prog='run')
        parser.add_argument('runid', nargs='?', default=None, type=str, help='Module name')
        parser.add_argument('--module', type=str, default=None, help='Filter results by module name')
        try:
            args = parser.parse_args(shlex.split(line))
            args = vars(args)
        except SystemExit:
            # argparse throws SystemExit on error, handle gracefully in CLI
            return
        if line == 'help':
            self._help_get_hc_result()
            return
        if args.get('runid', None):
            uri = self.rest_infra.valid_uri["list_health_check_runs"]
            results, error, code = self.rest_infra.sif_request(method='GET', uri=uri, timeout=30)
            if args.get('runid', None) not in results:
                print(f"\n[red]Error[/] : Run ID [yellow]{args.get('runid')}[/] not found\n")
                print(f"[yellow]Available Run IDs[/] : \n\n{', '.join(results)}\n")
                print()
                return
        try:
            if not args.get('runid', None):
                uri = self.rest_infra.valid_uri["get_current_healthcheck_results"]
            else:
                uri = self.rest_infra.valid_uri["get_runid_healthcheck_results"].replace("RUNID", args.get('runid'))
            results, error, code = self.rest_infra.sif_request(method='GET', uri=uri, timeout=30)
        except Exception as e:
            print(f"[red]Error in collection[/] : [yellow]Error[/] {e}")
            return
        if code != 200 or error:
            print(f"\n[red]Error retrieving health check result[/] : {error}\n")
            return
        self.print_healthcheck_results(results=results.get("results", []),module=args.get('module', None))
        print("")

    def print_healthcheck_results(self, results: list[dict], module: str = None) -> None:
        """
        Organize and print deduplicated healthcheck results as tables per module.

        Results sharing the same test ID and output message are collapsed into a
        single row; all affected node IPs are listed together in the Nodes column.
        Tests with state 'Error' are excluded from display.
        Colors: Pass=green, Warn/Warning=yellow, Fail=red, Skip=blue.
        """
        from collections import defaultdict

        # Group results by module (exclude Error state only)
        module_tests = defaultdict(list)
        for test in results:
            if test.get("state") == "Error":
                continue
            mod = test.get("module", "Unknown")
            module_tests[mod].append(test)

        if module not in module_tests and module is not None:
            print(f"\n[red]Error[/] : Module [yellow]{module}[/] not found in results\n")
            print(f"[yellow]Available Modules in Results[/] : {', '.join(module_tests.keys())}")
            return

        state_order = {"Fail": 0, "Warning": 1, "Warn": 1, "Pass": 2, "Skip": 3}
        state_color = {"Fail": "red", "Warning": "yellow", "Warn": "yellow",
                       "Pass": "green", "Skip": "blue"}

        modules_to_print = (
            [module] if module and module in module_tests
            else sorted(module_tests.keys())
        )

        tables = []
        for mod in modules_to_print:
            # ── Deduplicate by (testNumber, test-script, out-message, state) ──
            seen: dict = {}
            for t in module_tests[mod]:
                out_msg = t.get("out", "") or ""
                key = (str(t.get("testNumber", "")), t.get("test", ""), out_msg, t.get("state", ""))
                if key not in seen:
                    seen[key] = {
                        "test_number": str(t.get("testNumber", "")),
                        "out":         out_msg,
                        "state":       t.get("state", ""),
                        "severity":    str(t.get("severity", "")),
                        "nodes":       set(),
                    }
                nd = t.get("nodeData") or {}
                seen[key]["nodes"].add(nd.get("nodeIp", "unknown"))

            deduped = sorted(
                seen.values(),
                key=lambda x: (state_order.get(x["state"], 99), x["test_number"]),
            )

            table = Table(
                box=ROUNDED,
                show_header=True,
                header_style="bold yellow",
                border_style="cyan",
                padding=(0, 1),
                row_styles=["", "dim"],
                expand=False,
            )
            table.add_column("Test ID",  style="bold cyan",   no_wrap=True,  min_width=10)
            table.add_column("State",    style="bold",         no_wrap=True,  min_width=8)
            table.add_column("Severity", style="dim",          no_wrap=True,  min_width=6)
            table.add_column("Output",   style="white",        overflow="fold", max_width=60)
            table.add_column("Nodes",    style="bright_cyan",  overflow="fold", max_width=30)

            for row in deduped:
                color = state_color.get(row["state"], "white")
                table.add_row(
                    row["test_number"] or "—",
                    f"[{color}]{row['state']}[/{color}]",
                    row["severity"]    or "—",
                    row["out"]         or "—",
                    ", ".join(sorted(row["nodes"])),
                )
            state_counts = {k: sum(1 for d in deduped if d['state'] == k) for k in state_order}
            sub_parts = []
            for st, col in [("Pass","green"),("Warn","yellow"),("Warning","yellow"),("Fail","red"),("Skip","blue")]:
                n = state_counts.get(st, 0)
                if n:
                    sub_parts.append(f"[{col}]{st}:{n}[/{col}]")
            subtitle_str = "  ".join(sub_parts) if sub_parts else f"[dim]{len(deduped)} result(s)[/dim]"
            tables.append(Panel(
                table,
                title=f"[bold bright_blue] {mod.capitalize()} — Healthcheck Results [/]",
                subtitle=subtitle_str,
                border_style="bright_blue",
                padding=(1, 2),
            ))

        console = Console(record=True, color_system='truecolor', force_terminal=True)
        with console.capture() as capture:
            for item in tables:
                if item:
                    console.print(item)
                else:
                    console.print()
        self.ppaged(capture.get())

    def _help_get_hc_result(self) -> None:
        """Display help information for the get_health command."""
        print("""
        [yellow]Usage[/]:
            get_health <run_id>

        [blue]Description[/]:
            Retrieves and displays the result of a specific health check run identified by its run ID.

        [magenta]Examples[/]:
    
            ([blue]Odin Shell[/]) : get_healthcheck_result 1758561234567890123 --module software

                                                        [magenta]software[/] [bold white]Healthcheck Results[/]
            ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━┓
            ┃ [bold cyan]Test[/]                       ┃ [bold cyan]Test Num[/] ┃      [bold cyan]Inputs[/]      ┃      [bold cyan]State[/]     ┃  [bold cyan]Sev[/]  ┃ [bold cyan]Output[/] ┃ [bold cyan]Node Name[/]     ┃ [bold cyan]Node IP[/] ┃
            ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━┩
            │ command or script executed │ test num │ Inputs collected │ Pass/Fail/Warn │ 0,1,3 │ Reason │ node hostname │ node ip │                                  
            └────────────────────────────┴──────────┴──────────────────┴────────────────┴───────┴────────┴───────────────┴─────────┘
        """)    


    def _get_util_status(self, run_id: str = '') -> None:
        """Show async utility run status from /master/hcUtilXR/status.

        Args:
            run_id: Optional run ID to filter to a single entry.
        """
        print('')
        console = Console(record=True, color_system='truecolor', force_terminal=True)
        uri = self.rest_infra.valid_uri["get_util_xr_status"]
        try:
            data, error, code = self.rest_infra.sif_request(method='GET', uri=uri, timeout=30)
        except Exception as e:
            console.print(f"[red]Error fetching utility status[/] : {e}")
            return
        if code != 200 or error:
            console.print(f"[red]Error fetching utility status[/] (HTTP {code}) : {error}")
            return

        # Normalise: API may return a list of status dicts or a single dict
        if isinstance(data, dict):
            entries = list(data.values()) if not run_id else [data]
            # Also handle {runId: {...}} top-level map
            if all(isinstance(v, dict) for v in entries):
                pass  # already flat list of dicts
        elif isinstance(data, list):
            entries = data
        else:
            console.print(f"[yellow]Unexpected response format:[/] {data!r}")
            return

        def _entry_id(e):
            return str(e.get('utilId', e.get('hcUtilId', e.get('runId', ''))))

        def _sort_key(e):
            try:
                return int(_entry_id(e))
            except (TypeError, ValueError):
                return 0

        if run_id:
            # ── Detail view: all log entries for this run_id, in order ────────
            detail_entries = [e for e in entries if _entry_id(e) == str(run_id)]
            if not detail_entries:
                console.print(f"[red]No status found for run ID[/] [bold]{run_id}[/bold]\n")
                return

            rid = _entry_id(detail_entries[0])
            try:
                ts = datetime.fromtimestamp(int(rid) / 1_000_000_000).strftime("%Y-%m-%d %H:%M:%S")
            except Exception:
                ts = '—'

            # Build a timeline table — one row per log entry
            detail_table = Table(
                box=ROUNDED,
                show_header=True,
                header_style="bold yellow",
                border_style="cyan",
                padding=(0, 1),
                expand=False,
            )
            detail_table.add_column("#",       style="dim",          min_width=3,  no_wrap=True)
            detail_table.add_column("Status",  style="bright_green", min_width=12, no_wrap=True)
            detail_table.add_column("Message", style="white",        min_width=40)

            def _fmt_status(s: str) -> str:
                sl = s.lower()
                if sl in ('done', 'success', 'complete', 'finished'):
                    return f'[bright_green]{s}[/bright_green]'
                if sl in ('running', 'in_progress', 'started'):
                    return f'[yellow]{s}[/yellow]'
                if sl in ('error', 'failed', 'fail'):
                    return f'[red]{s}[/red]'
                return s

            for i, e in enumerate(detail_entries, 1):
                status  = str(e.get('status', e.get('state', '')))
                message = str(e.get('message', ''))
                detail_table.add_row(str(i), _fmt_status(status), message)

            # Header info above the timeline
            info_table = Table(box=None, show_header=False, padding=(0, 1), expand=False)
            info_table.add_column(style="bold yellow", min_width=12, no_wrap=True)
            info_table.add_column(style="white")
            info_table.add_row("Run ID",   f"[bold cyan]{rid}[/bold cyan]")
            info_table.add_row("Run Date", ts)
            e0 = detail_entries[0]
            if e0.get('utilName'):
                info_table.add_row("Module",  str(e0['utilName']))
            if e0.get('utilExec'):
                info_table.add_row("Utility", str(e0['utilExec']))

            panel = Panel(
                Group(info_table, Text(""), detail_table),
                title=f"[bold bright_blue] Utility Status · {rid} [/]",
                subtitle=f"[dim]{len(detail_entries)} log entr{'y' if len(detail_entries)==1 else 'ies'}[/dim]",
                border_style="bright_blue",
                padding=(1, 2),
            )
            with console.capture() as capture:
                console.print(panel)
            self.ppaged(capture.get())
            return

        # ── Summary table: most recent entry per utilId ───────────────────────
        # Walk the list in order; last write per ID wins (= most recent status).
        latest: dict[str, dict] = {}
        for e in entries:
            latest[_entry_id(e)] = e
        entries = sorted(latest.values(), key=_sort_key)

        def _fmt_status(s: str) -> str:
            sl = s.lower()
            if sl in ('done', 'success', 'complete', 'finished'):
                return f'[bright_green]{s}[/bright_green]'
            if sl in ('running', 'in_progress', 'started'):
                return f'[yellow]{s}[/yellow]'
            if sl in ('error', 'failed', 'fail'):
                return f'[red]{s}[/red]'
            return s

        table = Table(
            box=ROUNDED,
            show_header=True,
            header_style="bold yellow",
            border_style="cyan",
            padding=(0, 1),
            row_styles=["", "dim"],
            expand=False,
        )
        # Determine columns dynamically from first entry, putting key fields first
        _PRIORITY = ['utilId', 'utilName', 'utilExec', 'status', 'message',
                     'hcUtilId', 'runId', 'module', 'utility', 'state']
        sample    = entries[0] if entries else {}
        all_keys  = list(dict.fromkeys(
            [k for k in _PRIORITY if k in sample] +
            [k for k in sample   if k not in _PRIORITY]
        ))
        # Always show a Run Date column derived from the ID
        id_key = 'utilId' if 'utilId' in sample else ('hcUtilId' if 'hcUtilId' in sample else 'runId')

        col_styles = {
            id_key:      ('bold cyan',   22, True),
            'utilName':  ('yellow',      14, False),
            'utilExec':  ('white',       20, False),
            'module':    ('yellow',      14, False),
            'utility':   ('white',       20, False),
            'status':    ('bright_green',12, False),
            'state':     ('bright_green',12, False),
            'message':   ('dim',         50, False),
        }
        for k in all_keys:
            if k == id_key:
                table.add_column("Run ID",   style='bold cyan',   no_wrap=True, min_width=22)
            elif k == 'utilName':
                table.add_column("Module",   style='yellow',      min_width=14)
            elif k == 'utilExec':
                table.add_column("Utility",  style='white',       min_width=20)
            elif k == 'message':
                table.add_column("Command",  style='dim',         min_width=30, no_wrap=False)
            else:
                st, mw, nw = col_styles.get(k, ('white', 12, False))
                table.add_column(k.replace('_', ' ').title(), style=st, min_width=mw, no_wrap=nw)
        table.add_column("Run Date", style="dim", min_width=20)

        for e in entries:
            rid = str(e.get(id_key, ''))
            try:
                ts = datetime.fromtimestamp(int(rid) / 1_000_000_000).strftime("%Y-%m-%d %H:%M:%S")
            except Exception:
                ts = '[dim]—[/dim]'
            row = []
            for k in all_keys:
                v = str(e.get(k, '')) if e.get(k) is not None else ''
                if k in ('status', 'state'):
                    v = _fmt_status(v)
                row.append(v)
            row.append(ts)
            table.add_row(*row)

        panel = Panel(
            table,
            title="[bold bright_blue] Utility XR Status [/]",
            subtitle=f"[dim]{len(entries)} run(s)  •  [cyan]get utility status <run_id>[/cyan] for detail[/dim]",
            border_style="bright_blue",
            padding=(1, 2),
        )
        with console.capture() as capture:
            console.print(panel)
        self.ppaged(capture.get())


    def _list_results(self, line='') -> None:
        """List all available results from previous utility runs.

        Args:
            line (str): The command line input.
        """
        results:list[int] = []
        error:str = None
        code:int = 200
        if line == 'help':
            self._help_list_results()
            return
        print('')
        try:
            uri = self.rest_infra.valid_uri["list_util_runs"]
            results, error, code = self.rest_infra.sif_request(method='GET', uri=uri, timeout=30)
        except Exception as e:
            print(f"[red]Error in collection[/] : [yellow]Error[/] {e}")
            return
        console = Console(record=True, color_system='truecolor', force_terminal=True)
        renderables = []
        # Session async runs panel
        if self.xr_runs:
            xr_table = Table(
                box=ROUNDED,
                show_header=True,
                header_style="bold yellow",
                border_style="cyan",
                padding=(0, 1),
                row_styles=["", "dim"],
                expand=False,
            )
            xr_table.add_column("Run ID",  style="bold cyan", no_wrap=True, min_width=22)
            xr_table.add_column("Details", style="white",     max_width=70)
            for xr_id, xr_details in self.xr_runs.items():
                xr_table.add_row(str(xr_id), xr_details)
            renderables.append(Panel(
                xr_table,
                title="[bold bright_blue] Async Runs — Current Session [/]",
                subtitle=f"[dim]{len(self.xr_runs)} run(s)  •  [cyan]get utility <run_id>[/cyan] to view[/dim]",
                border_style="bright_blue",
                padding=(1, 2),
            ))
        # All API results panel
        table = Table(
            box=ROUNDED,
            show_header=True,
            header_style="bold yellow",
            border_style="cyan",
            padding=(0, 1),
            row_styles=["", "dim"],
            expand=False,
        )
        table.add_column("Run ID",   style="bold cyan", no_wrap=True, min_width=22)
        table.add_column("Module",   style="yellow",    min_width=14)
        table.add_column("Utility",  style="white",     min_width=20)
        table.add_column("Run Date", style="dim",       min_width=20)
        for r in results:
            # API may return either a plain int ID or a dict {hcUtilId, module, utility}
            if isinstance(r, dict):
                run_id_raw = r.get('hcUtilId', '')
                module_str = str(r.get('module',  ''))
                util_str   = str(r.get('utility', ''))
            else:
                run_id_raw = r
                module_str = ''
                util_str   = ''
            try:
                run_dt = datetime.fromtimestamp(int(run_id_raw) / 1_000_000_000)
                run_dt_str = run_dt.strftime("%Y-%m-%d %H:%M:%S")
            except Exception:
                run_dt_str = "[dim]—[/dim]"
            table.add_row(str(run_id_raw), module_str, util_str, run_dt_str)
        renderables.append(Panel(
            table,
            title="[bold bright_blue] Utility Run Results [/]",
            subtitle=f"[dim]{len(results)} result(s)  •  [cyan]get utility <run_id>[/cyan] to view[/dim]",
            border_style="bright_blue",
            padding=(1, 2),
        ))
        with console.capture() as capture:
            for item in renderables:
                console.print(item)
        self.ppaged(capture.get())


    def _help_list_results(self) -> None:
        """
        Display help information for the list_results command.

        Args:
            None

        Returns:
            None
        """
        print("""
        [yellow]Usage[/]:
            list_results

        [blue]Description[/]:
            Lists all available results from previous utility runs, including run ID, module, utility, and status.

        [magenta]Examples[/]:
    
            ([blue]Odin Shell[/]) : list_results

            [green]Asynchronous Runs during current session[/] : 

            [yellow]1758554947246857467[/] : [green]gflag [yellow]list_all_gflags [blue]nexus 

            [yellow]Optional Args[/]
                [green]all        [/]: False
                [green]json       [/]: False
                [green]timeout    [/]: 360
                [green]no-timeout [/]: False


            [yellow]All Available Results[/] : 

            ┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
            ┃       [magenta]Run ID[/]        ┃      [magenta]Run Date[/]       ┃
            ┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
            │ [yellow]1758552859997998713[/] │ [green]2025-09-22 07:54:19[/] │
            └─────────────────────┴─────────────────────┘
        """)


    def _get_result(self, line='') -> None:
        """Retrieve and display the result of a specific utility run by its run ID.

        Args:
            line (str): The command line input containing the run ID.
        """
        if line == 'help':
            self._help_get_result()
            return
        print('')
        try:
            uri = self.rest_infra.valid_uri["get_util_results"].replace("RUNID", line)
            results, error, code = self.rest_infra.sif_request(method='GET', uri=uri, timeout=30)
        except Exception as e:
            print(f"[red]Error in collection[/] : [yellow]Error[/] {e}")
            return
        if code != 200 or error:
            print(f"\n[red]Error retrieving result[/] : {error}\n")
            return
        timestamp = results.get('timestamp', 'Undefined')
        data = results.get('data', {})
        match data:
            case {'info': info} if info is not None:
                print(f"\n[green]Run[/] {line} [green]Info[/] : {data['info']}\n")
            case _:
                self.cli_print.print_output(data=data, dataType='json', dataFormat='json')
        print("")


    def _complete_get_result(self, text, line, begidx, endidx) -> list[str]:
        """
        complete_get_result attempts to complete an incomplete line of get_result

        if any line starts with get_result, but is incomplete, this will do a search on all run ids and either replace or provide all matching results

        Args:
            text (None): Blank Variable passed
            line (String): Full command line
            begidx (Int): start of the missing text
            endidx (Int): end of missing text

        Returns:
            String: full result from the find or None
        """
        result = []
        line = line.split()
        try:
            # Use a 30-second TTL cache to avoid hitting the API on every Tab press
            cache_ts, cached_results = self._result_cache
            if time.time() - cache_ts > 30:
                uri = self.rest_infra.valid_uri["list_util_runs"]
                fresh, error, code = self.rest_infra.sif_request(method='GET', uri=uri, timeout=30)
                if code == 200 and isinstance(fresh, list):
                    cached_results = [str(r) for r in fresh]
                    self._result_cache = (time.time(), cached_results)
            results = cached_results
        except Exception as e:
            print(f"[red]Error in collection[/] : [yellow]Error[/] {e}")
            return
        results = [str(r) for r in results]
        r = re.compile(text)
        # If length of the line is 1 or the second word is not a run id
        if len(line) == 1 or (len(line) > 1 and line[1] not in results):
            result = list(filter(r.match, results))
        # If result is 1, strip quotes (if needed)
        if len(result) == 1:
            result = [result[0].strip('\"')]
        return result


    def _help_get_result(self) -> None:
        """
        Display help information for the get_result command.
        
        Args:
            None

        Returns:
            None
        """
        print("""
        [yellow]Usage[/]:
            get_result <run_id>

        [blue]Description[/]:
            Retrieves and displays the result of a specific utility run identified by its run ID.

        [magenta]Examples[/]:
    
            ([blue]Odin Shell[/]) : get_result 1758554741012142432 

            {
            "nexus": [
                    {
                        "Name": "enable_licensing_monitor",
                        "Reason": "Cluster Creation",
                        "Time": "09/17/2025, 15:46:20",
                        "Value": "false"
                    }
                ]
            }
        """)


    def complete_help(self,text,line,begidx,endidx) -> list[str]:
        """Complete the help command.

        Args:
            text (str): The text to complete.
            line (str): The full command line.
            begidx (int): The start index of the incomplete text.
            endidx (int): The end index of the incomplete text.

        Returns:
            list[str]: A list of possible completions.
        """
        result = []
        try:
            r = re.compile(text)
            result = list(filter(r.match, self.commands))
        except Exception as e:
            print(f"\n[red]Error in tab completion[/] : [yellow]help {' '.join(line)}[/]\n")
            self.do_help(test=False)
        return result


    def do_clear(self, line):
        """
        do_clear clears the shell screen

        Args:
            line (String): Not used

        Returns:
            None
        """
        os.system('clear')

    def help_clear(self) -> None:
        """Display help information for the clear command."""
        print("""
        [yellow]Usage[/]:
            clear

        [blue]Description[/]:
            Clears the terminal screen.

        [magenta]Examples[/]:

            ([blue]Odin Shell[/]) : clear

            (screen is cleared)
        """)

    def get_names(self) -> list[str]:
        """Get a list of command names.

        Returns:
            list[str]: A list of command names.
        """
        return [n for n in dir(self.__class__) if n not in ('do_EOF','do_exit','do_quit')]


    def do_exit(self,line):
        return True

    def help_exit(self) -> None:
        """Display help information for the exit command."""
        print("""
        [yellow]Usage[/]:
            exit

        [blue]Description[/]:
            Exits the Odin Shell, cleaning up all resources.
            Equivalent to [yellow]quit[/] or pressing [yellow]Ctrl+D[/].

        [magenta]Examples[/]:

            ([blue]Odin Shell[/]) : exit

            Goodbye!
        """)

    def do_quit(self,line):
        return True

    def help_quit(self) -> None:
        """Display help information for the quit command."""
        print("""
        [yellow]Usage[/]:
            quit

        [blue]Description[/]:
            Exits the Odin Shell, cleaning up all resources.
            Equivalent to [yellow]exit[/] or pressing [yellow]Ctrl+D[/].

        [magenta]Examples[/]:

            ([blue]Odin Shell[/]) : quit

            Goodbye!
        """)


    def do_EOF(self,line):
        return True

def _print_motd(console) -> None:
    """Print the Odin Shell MOTD banner using rich design language."""
    from rich.table import Table as _Table

    def _section(title: str, rows: list) -> Group:
        tbl = _Table.grid(padding=(0, 2))
        tbl.add_column(style="cyan", min_width=42, no_wrap=True)
        tbl.add_column(style="dim white")
        for cmd, desc in rows:
            tbl.add_row(f"  {cmd}", desc)
        return Group(
            Text(f"  {title}", style="bold bright_blue"),
            tbl,
        )

    body = Group(
        Text(""),
        Text(f"  Odin Debug Shell  \u00b7  v{Constants.SHELL_VERSION}", style="dim"),
        Text(""),
        Rule(style="dim cyan"),
        Text(""),
        _section("Run", [
            ("run <module> <utility>",     "Execute a utility"),
            ("run healthcheck [mod,...]",  "Run a health check (comma/space separated)"),
        ]),
        Text(""),
        Rule(style="dim cyan"),
        Text(""),
        _section("Discover", [
            ("list",                       "Show all available modules"),
            ("list <module>",              "Show utilities in a module"),
            ("list healthcheck",           "Show all health check modules"),
        ]),
        Text(""),
        Rule(style="dim cyan"),
        Text(""),
        _section("Results", [
            ("get healthcheck runs",           "List all health check run IDs"),
            ("get healthcheck <run_id>",       "Show a specific health check result"),
            ("get utility runs",               "List all utility run results"),
            ("get utility status",             "Show live status for all async runs"),
            ("get utility status <run_id>",    "Show live status for a specific async run"),
            ("get utility <run_id>",           "Show a specific utility result"),
        ]),
        Text(""),
        Rule(style="dim cyan"),
        Text(""),
        _section("Iris", [
            ("iris login",                 "Authenticate with Iris (30-min session)"),
            ("iris shell",                 "Drop into iris_cli (authenticates if needed)"),
            ("iris logout",                "Log out of Iris"),
        ]),
        Text(""),
        Rule(style="dim cyan"),
        Text(""),
        _section("Shell", [
            ("manual [topic]",    "Browse the documentation (q to exit pager)"),
            ("version",           "Show current version"),
            ("release_notes",     "View release notes"),
            ("refresh",           "Refresh the module cache"),
            ("history",           "Show command history"),
            ("clear",             "Clear the screen"),
            ("help [command]",    "Show help for a command"),
            ("exit",              "Exit the shell"),
        ]),
        Text(""),
        Text.from_markup("  [dim]Type [cyan]help <command>[/cyan][dim] for detailed usage.[/dim]"),
        Text(""),
    )
    panel = Panel(
        body,
        title="[bold cyan]Odin Shell[/bold cyan]",
        border_style="cyan",
        expand=False,
    )
    console.print()
    console.print(panel)
    console.print()


def main(**kwargs) -> None:
    ds = secureDebug(kwargs)
    _print_motd(ds.console)
    ds.cmdloop()

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument('--dev', action='store_true', help='Enable test mode', default=False)
    args, unknown = parser.parse_known_args()
    main(**vars(args))