Add description and methods_description infrastructure

this allows override of the default strings to show up in the jmp shell CLI.

the Driver descriptions can be customized with:
exporter:
  driver_x:
    type: x
    description: "this driver does x"
    methods_description:
      method1: "this method does y"
      method2: "this method does z"

Client-side changes:
- Add DriverClickGroup class in client/decorators.py for CLI generation
- Add description and methods_description field to DriverClient, updated from GetReport from server

Server-side changes:
- Include methods_description in DriverInstanceReport
- Extend @export and @exportstream with optional help= parameter
- Add desscription and methods_description field to Driver base class

The infrastructure is using a single DriverInstanceReport message to save on RPC calls.

Author: michalskrivanek

packages/jumpstarter/jumpstarter/client/base.py

@@ -33,6 +33,12 @@ class DriverClient(AsyncDriverClient):
     portal: BlockingPortal
     stack: ExitStack
 
+    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

@@ -51,13 +51,16 @@ async def client_from_channel(
         report = reports[index]
 
         client_class = import_class(report.labels["jumpstarter.dev/client"], allow, unsafe)
+
         client = client_class(
             uuid=UUID(report.uuid),
             labels=report.labels,
             stub=stub,
             portal=portal,
             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/client/decorators.py

@@ -0,0 +1,83 @@
+"""
+Client-side Click group helpers for building driver CLIs.
+"""
+
+from typing import Any, Callable
+
+import click
+
+
+class DriverClickGroup(click.Group):
+    """
+    Custom Click Group to use methods_description for command help.
+    Usage:
+        def cli(self):
+            # client.description from server or help= fallback
+            base = DriverClickGroup(self, help="Default driver description")
+
+            # Add options elegantly
+            base.add_option("--log-level", type=click.Choice([...]), help="...")
+
+            # methods_description['on'] from server or help= fallback
+            @base.command(help="Power on")
+            def on():
+                self.on()
+
+            return base
+    """
+
+    def __init__(self, client: Any, *args: Any, **kwargs: Any) -> None:
+        """
+        Initialize a DriverClickGroup bound to a client.
+
+        :param client: DriverClient instance (provides methods_description and description)
+        :param args: Arguments passed to click.Group
+        :param kwargs: Keyword arguments passed to click.Group (help= is used as fallback)
+        """
+        # Use client.description if available, otherwise use provided help
+        if 'help' in kwargs:
+            kwargs['help'] = getattr(client, 'description', None) or kwargs['help']
+
+        super().__init__(*args, **kwargs)
+        self.client = client
+
+    def add_option(self, *param_decls: str, **kwargs: Any) -> 'DriverClickGroup':
+        """
+        Add a Click option to this group (chainable).
+
+        Usage:
+            base = DriverClickGroup(self, help="...")
+            base.add_option("--log-level", type=click.Choice([...]), help="...")
+
+        :param param_decls: Option names (e.g., "--log-level", "-l")
+        :param kwargs: Click Option parameters (type, help, callback, etc.)
+        :return: self for chaining
+        """
+        self.params.append(click.Option(list(param_decls), **kwargs))
+        return self
+
+    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

packages/jumpstarter/jumpstarter/driver/base.py

@@ -23,6 +23,7 @@
 
 from .decorators import (
     MARKER_DRIVERCALL,
+    MARKER_HELP,
     MARKER_MAGIC,
     MARKER_STREAMCALL,
     MARKER_STREAMING_DRIVERCALL,
@@ -72,6 +73,12 @@ class Driver(
     resources: dict[UUID, Any] = field(default_factory=dict, init=False)
     """Dict of client side resources"""
 
+    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)
 
@@ -82,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()
@@ -206,6 +230,8 @@ def report(self, *, root=None, parent=None, name=None):
             | self.extra_labels()
             | ({"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,37 @@
+"""
+Server-side decorators for exporting driver methods.
+"""
+
 from inspect import isasyncgenfunction, iscoroutinefunction, isfunction, isgeneratorfunction
-from typing import Final
+from typing import Callable, Final
 
 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):
-    """
-    Decorator for exporting method as stream
-    """
-    setattr(func, MARKER_STREAMCALL, MARKER_MAGIC)
-    return func
+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