From b816dc5e54907e2686edfd532c67dde593fef9a3 Mon Sep 17 00:00:00 2001
From: Goffi <goffi@goffi.org>
Date: Sun, 31 Aug 2025 12:34:37 +0200
Subject: [PATCH] cli (pubsub): List support first draft + doc:

Basic support for listing hierarchy of nodes with pubsub extended discovery. Nodes are
displayed as a tree, depth can be specified.

rel 463
---
 doc/libervia-cli/pubsub.rst | 26 ++++++++++++++++
 libervia/cli/cmd_pubsub.py  | 59 +++++++++++++++++++++++++++++++++++++
 2 files changed, 85 insertions(+)

diff --git a/doc/libervia-cli/pubsub.rst b/doc/libervia-cli/pubsub.rst
index f731fdac..9095bbad 100644
--- a/doc/libervia-cli/pubsub.rst
+++ b/doc/libervia-cli/pubsub.rst
@@ -117,6 +117,32 @@ Rename a PubSub item with ID ``123`` to ``456``::
 
   $ li pubsub rename -n some_node -i 123 456
 
+.. _li_pubsub_list:
+
+list
+====
+
+List PubSub nodes and items.
+
+By default, this command will display a tree view of the nodes and items available on the
+specified service.
+
+.. note::
+
+   The current implementation provides a basic tree view of nodes. Future versions will
+   include enhanced formatting options and additional filtering capabilities.
+
+example
+-------
+
+List all nodes and items on a pubsub service::
+
+  $ li pubsub list -s pubsub.example.net
+
+List nodes and items for a specific node::
+
+  $ li pubsub list -s pubsub.example.net -n some_node
+
 subscribe
 =========
 
diff --git a/libervia/cli/cmd_pubsub.py b/libervia/cli/cmd_pubsub.py
index 5d107a48..2cfa0210 100644
--- a/libervia/cli/cmd_pubsub.py
+++ b/libervia/cli/cmd_pubsub.py
@@ -26,6 +26,7 @@ import subprocess
 import asyncio
 import json
 from . import base
+from rich.tree import Tree
 from libervia.backend.core.i18n import _
 from libervia.backend.core import exceptions
 from libervia.cli.constants import Const as C
@@ -1566,6 +1567,63 @@ class Rename(base.CommandBase):
             self.host.quit(C.EXIT_OK)
 
 
+class List(base.CommandBase):
+
+    def __init__(self, host):
+        extra_outputs = {"default": self.default_output}
+        base.CommandBase.__init__(
+            self,
+            host,
+            "list",
+            use_pubsub=True,
+            use_output=C.OUTPUT_COMPLEX,
+            extra_outputs=extra_outputs,
+            pubsub_flags={},
+            help=_("list nodes and items"),
+        )
+
+    def add_parser_options(self):
+        self.parser.add_argument(
+            "-d",
+            "--depth",
+            type=int,
+            default=0,
+            help=_("recursion depth level (DEFAULT: 0)"),
+        )
+
+    async def start(self):
+        options = {
+            "depth": self.args.depth
+        }
+        try:
+            result_s = await self.host.bridge.ps_disco_get(
+                self.args.service,
+                self.args.node,
+                data_format.serialise(options),
+                self.profile,
+            )
+        except Exception as e:
+            self.disp(f"Can't list: {e}.", error=True)
+            self.host.quit(C.EXIT_BRIDGE_ERRBACK)
+        else:
+            result = data_format.deserialise(result_s, type_check=list)
+            await self.output(result)
+            self.host.quit(C.EXIT_OK)
+
+    def recursive_tree(self, item_data: dict) -> Tree:
+        node_tree = Tree(item_data["name"])
+        children = item_data.get("children", [])
+        for child in children:
+            node_tree.add(self.recursive_tree(child))
+        return node_tree
+
+
+    def default_output(self, data: list) -> None:
+        """Output the node as a tree view."""
+        for item in data:
+            self.console.print(self.recursive_tree(item))
+
+
 class Subscribe(base.CommandBase):
     def __init__(self, host):
         base.CommandBase.__init__(
@@ -3064,6 +3122,7 @@ class Pubsub(base.CommandBase):
         Delete,
         Edit,
         Rename,
+        List,
         Subscribe,
         Unsubscribe,
         Subscriptions,