API: add show clan to retrieve the buildClan meta

pkgs/clan-cli/clan_cli/__init__.py

@@ -8,6 +8,7 @@ from typing import Any
 
 # These imports are unused, but necessary for @API.register to run once.
 from clan_cli.api import directory
+from clan_cli.flakes import show
 
 __all__ = ["directory"]
 
@@ -112,8 +113,17 @@ For more detailed information, visit: https://docs.clan.lol
         ),
         formatter_class=argparse.RawTextHelpFormatter,
     )
+
     subparsers = parser.add_subparsers()
 
+    # Commands directly under the root i.e. "clan show"
+    show_parser = subparsers.add_parser(
+        "show",
+        help="Show the clan meta if present.",
+        description="Final meta results from clan/meta.json and flake arguments.",
+    )
+    show_parser.set_defaults(func=show.show_command)
+
     parser_backups = subparsers.add_parser(
         "backups",
         help="manage backups of clan machines",

pkgs/clan-cli/clan_cli/flakes/show.py

@@ -0,0 +1,64 @@
+import argparse
+import dataclasses
+import json
+import logging
+from pathlib import Path
+
+from clan_cli.api import API
+from clan_cli.errors import ClanCmdError, ClanError
+
+from ..cmd import run_no_stdout
+from ..nix import nix_eval
+
+log = logging.getLogger(__name__)
+
+
+@dataclasses.dataclass
+class ClanMeta:
+    name: str
+    description: str | None
+    icon: str | None
+
+
+@API.register
+def show_clan(uri: str | Path) -> ClanMeta:
+    cmd = nix_eval(
+        [
+            f"{uri}#clanInternals.meta",
+            "--json",
+        ]
+    )
+    res = "{}"
+    try:
+        proc = run_no_stdout(cmd)
+        res = proc.stdout.strip()
+    except ClanCmdError:
+        raise ClanError(
+            "Clan might not have meta attributes",
+            location=f"show_clan {uri}",
+            description="Evaluation failed on clanInternals.meta attribute",
+        )
+
+    clan_meta = json.loads(res)
+    return ClanMeta(
+        name=clan_meta.get("name"),
+        description=clan_meta.get("description", None),
+        icon=clan_meta.get("icon", None),
+    )
+
+
+def show_command(args: argparse.Namespace) -> None:
+    flake_path = Path(args.flake).resolve()
+    meta = show_clan(flake_path)
+
+    print(f"Name: {meta.name}")
+    print(f"Description: {meta.description or ''}")
+    print(f"Icon: {meta.icon or ''}")
+
+
+def register_parser(parser: argparse.ArgumentParser) -> None:
+    parser.set_defaults(func=show_command)
+    parser.add_argument(
+        "show",
+        help="Show",
+    )