add methods_description and extend decorators

to allow driver-provided help text for exported methods.
Map od methods and their descriptions is added to GetReport to save on RPC calls.

Author: michalskrivanek

packages/jumpstarter/jumpstarter/client/base.py

@@ -36,6 +36,9 @@ class DriverClient(AsyncDriverClient):
     description: str | None = None
     """Driver description from GetReport(), used for CLI help text"""
 
+    methods_description: dict[str, str] = field(default_factory=dict)
+    """Map of method names to their help descriptions from GetReport()"""
+
     def call(self, method, *args):
         """
         Invoke driver call

packages/jumpstarter/jumpstarter/client/client.py

@@ -60,6 +60,7 @@ async def client_from_channel(
             stack=stack.enter_context(ExitStack()),
             children={reports[k].labels["jumpstarter.dev/name"]: clients[k] for k in topo[index]},
             description=getattr(report, 'description', None) or None,
+            methods_description=getattr(report, 'methods_description', {}) or {},
         )
 
         clients[index] = client

packages/jumpstarter/jumpstarter/driver/base.py

@@ -23,6 +23,7 @@
 
 from .decorators import (
     MARKER_DRIVERCALL,
+    MARKER_HELP,
     MARKER_MAGIC,
     MARKER_STREAMCALL,
     MARKER_STREAMING_DRIVERCALL,
@@ -75,6 +76,9 @@ class Driver(
     description: str | None = None
     """Custom description for the driver (shown in CLI help)"""
 
+    methods_description: dict[str, str] = field(default_factory=dict, init=False)
+    """Map of method names to their help descriptions"""
+
     log_level: str = "INFO"
     logger: logging.Logger = field(init=False)
 
@@ -85,6 +89,23 @@ def __post_init__(self):
         self.logger = logging.getLogger(self.__class__.__name__)
         self.logger.setLevel(self.log_level)
 
+        # Collect help texts from decorated methods
+        self._collect_methods_description()
+
+    def _collect_methods_description(self):
+        """Collect help texts from @export and @exportstream decorated methods"""
+        for name in dir(self):
+            if name.startswith('_'):
+                continue
+
+            try:
+                method = getattr(self, name)
+                if callable(method) and hasattr(method, MARKER_HELP):
+                    help_text = getattr(method, MARKER_HELP)
+                    self.methods_description[name] = help_text
+            except Exception:
+                continue
+
     def close(self):
         for child in self.children.values():
             child.close()
@@ -210,6 +231,7 @@ def report(self, *, root=None, parent=None, name=None):
             | ({"jumpstarter.dev/client": self.client()})
             | ({"jumpstarter.dev/name": name} if name else {}),
             description=self.description or None,
+            methods_description=self.methods_description or {},
         )
 
     def enumerate(self, *, root=None, parent=None, name=None):

packages/jumpstarter/jumpstarter/driver/decorators.py

@@ -1,28 +1,88 @@
 from inspect import isasyncgenfunction, iscoroutinefunction, isfunction, isgeneratorfunction
-from typing import Final
+from typing import Any, Callable, Final
+
+import click
 
 MARKER_MAGIC: Final[str] = "07c9b9cc"
 MARKER_DRIVERCALL: Final[str] = "marker_drivercall"
 MARKER_STREAMCALL: Final[str] = "marker_streamcall"
 MARKER_STREAMING_DRIVERCALL: Final[str] = "marker_streamingdrivercall"
+MARKER_HELP: Final[str] = "marker_help"
 
 
-def export(func):
-    """
-    Decorator for exporting method as driver call
-    """
-    if isasyncgenfunction(func) or isgeneratorfunction(func):
-        setattr(func, MARKER_STREAMING_DRIVERCALL, MARKER_MAGIC)
-    elif iscoroutinefunction(func) or isfunction(func):
-        setattr(func, MARKER_DRIVERCALL, MARKER_MAGIC)
-    else:
-        raise ValueError(f"unsupported exported function {func}")
-    return func
+def export(func: Callable | None = None, *, help: str | None = None) -> Callable:
+    """Decorator for exporting method as driver call"""
+    def decorator(f: Callable) -> Callable:
+        if isasyncgenfunction(f) or isgeneratorfunction(f):
+            setattr(f, MARKER_STREAMING_DRIVERCALL, MARKER_MAGIC)
+        elif iscoroutinefunction(f) or isfunction(f):
+            setattr(f, MARKER_DRIVERCALL, MARKER_MAGIC)
+        else:
+            raise ValueError(f"unsupported exported function {f}")
+        if help is not None:
+            setattr(f, MARKER_HELP, help)
+        return f
+    return decorator(func) if func else decorator
+
 
+def exportstream(func: Callable | None = None, *, help: str | None = None) -> Callable:
+    """Decorator for exporting method as stream"""
+    def decorator(f: Callable) -> Callable:
+        setattr(f, MARKER_STREAMCALL, MARKER_MAGIC)
+        if help is not None:
+            setattr(f, MARKER_HELP, help)
+        return f
+    return decorator(func) if func else decorator
 
-def exportstream(func):
+
+class DriverClickGroup(click.Group):
     """
-    Decorator for exporting method as stream
+    Custom Click Group to use methods_description for command help.
+
+    Usage:
+        def cli(self):
+            base = DriverClickGroup(self, help="Default driver description")
+
+            @base.command()  # Automatically uses string from methods_description['on']
+            def on():
+                self.on()
+
+            return base
     """
-    setattr(func, MARKER_STREAMCALL, MARKER_MAGIC)
-    return func
+
+    def __init__(self, client: Any, *args: Any, **kwargs: Any) -> None:
+        """
+        Initialize a DriverClickGroup bound to a client.
+
+        :param client: DriverClient instance (provides methods_description)
+        :param args: Arguments passed to click.Group
+        :param kwargs: Keyword arguments passed to click.Group
+        """
+        super().__init__(*args, **kwargs)
+        self.client = client
+
+    def command(self, *args: Any, **kwargs: Any) -> Callable:
+        """
+        Decorator to register a client-side command with automatic help text.
+
+        Priority order for help text:
+        1. methods_description from server (highest priority)
+        2. help= parameter explicitly provided in @base.command(help="...")
+        3. Empty string (fallback)
+        """
+        def decorator(f: Callable) -> click.Command:
+            # Determine command name (from kwargs or function name)
+            name = kwargs.get('name') or f.__name__
+
+            # Priority order for help text:
+            # 1. methods_description from server
+            # 2. help= parameter explicitly provided by client
+            # 3. Empty string
+            if name in self.client.methods_description:
+                kwargs['help'] = self.client.methods_description[name]
+            elif 'help' not in kwargs:
+                kwargs['help'] = ''
+
+            return super(DriverClickGroup, self).command(*args, **kwargs)(f)
+
+        return decorator