feat(cli): add fdp device list/show/use

Removes the need to hand-edit ~/.fdp/config.toml when a default is wanted.
`fdp catalog` remains as a deprecated alias.

Author: sammuli

fdp/cli.py

@@ -21,9 +21,9 @@
 from datetime import datetime, timezone
 from pathlib import Path
 
-from . import auth
+from . import auth, config
 from .catalog import catalog
-from .devices import active_handles, resolve_for_capability
+from .devices import CAPABILITIES, active_handles, resolve_for_capability
 from .environment import (
     compose_device_config, resolve_bearer_token, setup_environment,
 )
@@ -154,6 +154,39 @@ def do_catalog(args) -> None:
         raise ValueError(f"Unknown catalog subcommand: {args.subcmd!r}")
 
 
+def do_device(args) -> None:
+    if args.device_command == "list":
+        for name in catalog.names():
+            handle = catalog[name]
+            caps = [cap for cap, (predicate, _) in CAPABILITIES.items()
+                    if predicate(handle)]
+            print(f"{name}\t{handle.description}\t"
+                  f"[{', '.join(caps) if caps else 'none'}]")
+    elif args.device_command == "show":
+        import yaml
+        print(yaml.safe_dump(catalog[args.name].schema.model_dump(),
+                              sort_keys=False))
+    elif args.device_command == "use":
+        if args.clear:
+            config.set_default_device(None)
+            print("Cleared the default device.")
+            return
+        if args.name is None:
+            print("Error: `fdp device use` needs a device name "
+                  "(or --clear).", file=sys.stderr)
+            sys.exit(1)
+        if args.name not in catalog:
+            print(f"Error: unknown device {args.name!r}. Registered: "
+                  f"{', '.join(catalog.names())}", file=sys.stderr)
+            sys.exit(1)
+        config.set_default_device(args.name)
+        print(f"Default device set to '{args.name}' in "
+              f"{config.config_path()}.")
+    else:
+        raise ValueError(
+            f"Unknown device subcommand: {args.device_command!r}")
+
+
 def do_skills(args) -> None:
     skill_dirs = discover_skill_dirs()
     backend_arg = getattr(args, "backend", "claude")
@@ -312,13 +345,26 @@ def build_parser() -> argparse.ArgumentParser:
                        help="The path whose contents will be listed")
     p_ls.set_defaults(func=do_ls)
 
-    p_cat = sub.add_parser("catalog", help="Inspect the tokamak catalog")
+    p_cat = sub.add_parser("catalog",
+                            help="(deprecated) alias for `fdp device`")
     cat_sub = p_cat.add_subparsers(dest="subcmd", required=True)
     cat_sub.add_parser("list", help="List tokamak names and descriptions")
     show = cat_sub.add_parser("show", help="Print a tokamak's full catalog YAML")
     show.add_argument("name")
     p_cat.set_defaults(func=do_catalog, needs_env=False)
 
+    p_dev = sub.add_parser("device", help="Inspect and select devices")
+    dev_sub = p_dev.add_subparsers(dest="device_command", required=True)
+    dev_sub.add_parser("list", help="List devices and their capabilities")
+    dev_show = dev_sub.add_parser("show", help="Print a device's catalog YAML")
+    dev_show.add_argument("name")
+    dev_use = dev_sub.add_parser(
+        "use", help="Record a default device in ~/.fdp/config.toml")
+    dev_use.add_argument("name", nargs="?", default=None)
+    dev_use.add_argument("--clear", action="store_true",
+                          help="Remove the recorded default device.")
+    p_dev.set_defaults(func=do_device, needs_env=False)
+
     p_sk = sub.add_parser("skills",
                            help="Manage AI assistant skills")
     sk_sub = p_sk.add_subparsers(dest="skills_command", required=True)

tests/test_device_command.py

@@ -0,0 +1,60 @@
+# Copyright 2024 General Atomics
+# Licensed under the Apache License, Version 2.0.
+
+"""The `fdp device` subcommand group."""
+
+import contextlib
+import io
+import unittest
+from unittest import mock
+
+from test_capabilities import CatalogFixture, _D3D_YAML, _MAST_YAML
+
+
+class TestDeviceCommand(CatalogFixture):
+    YAMLS = (("d3d", _D3D_YAML), ("mast", _MAST_YAML))
+
+    def _run(self, argv):
+        from fdp import cli
+        out = io.StringIO()
+        with contextlib.redirect_stdout(out):
+            cli.main(argv)
+        return out.getvalue()
+
+    def test_list_shows_names_and_capabilities(self):
+        text = self._run(["device", "list"])
+        self.assertIn("d3d", text)
+        self.assertIn("mast", text)
+        self.assertIn("origin", text)
+        self.assertIn("bearer", text)
+
+    def test_show_prints_yaml(self):
+        text = self._run(["device", "show", "d3d"])
+        self.assertIn("name: d3d", text)
+
+    def test_use_writes_config_and_takes_effect(self):
+        from fdp.config import read_default_device
+        from fdp.devices import explicit_device_name
+        self._run(["device", "use", "mast"])
+        self.assertEqual(read_default_device(), "mast")
+        self.assertEqual(explicit_device_name(), "mast")
+
+    def test_use_clear_removes_the_setting(self):
+        from fdp.config import read_default_device
+        self._run(["device", "use", "mast"])
+        self._run(["device", "use", "--clear"])
+        self.assertIsNone(read_default_device())
+
+    def test_use_rejects_unknown_device(self):
+        from fdp import cli
+        stderr = io.StringIO()
+        with self.assertRaises(SystemExit) as ctx, \
+                contextlib.redirect_stderr(stderr):
+            cli.main(["device", "use", "nosuchdevice"])
+        self.assertEqual(ctx.exception.code, 1)
+        self.assertIn("nosuchdevice", stderr.getvalue())
+        self.assertNotIn("['", stderr.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()