update and cleanup repo

SYS/cmdlet_spec.py

@@ -77,6 +77,50 @@ def QueryArg(
     )
 
 
+def collect_registered_cmdlet_names(
+    cmdlet_obj: Any,
+    *,
+    fallback_name: Optional[str] = None,
+) -> List[str]:
+    """Return normalized registration keys for a cmdlet object.
+
+    Prefers the cmdlet object's own `_collect_names()` implementation when
+    available, then normalizes names to the registry key form used by callers.
+    """
+
+    raw_names: List[Any] = []
+
+    collector = getattr(cmdlet_obj, "_collect_names", None)
+    if callable(collector):
+        try:
+            raw_names.extend(list(collector() or []))
+        except Exception:
+            pass
+
+    if fallback_name:
+        raw_names.append(fallback_name)
+
+    if not raw_names:
+        raw_name = getattr(cmdlet_obj, "name", None)
+        if raw_name:
+            raw_names.append(raw_name)
+        for alias_attr in ("alias", "aliases"):
+            alias_values = getattr(cmdlet_obj, alias_attr, None)
+            if not alias_values:
+                continue
+            raw_names.extend(list(alias_values))
+
+    seen: Set[str] = set()
+    normalized_names: List[str] = []
+    for raw_name in raw_names:
+        key = str(raw_name or "").replace("_", "-").lower().strip()
+        if not key or key in seen:
+            continue
+        seen.add(key)
+        normalized_names.append(key)
+    return normalized_names
+
+
 class SharedArgs:
     """Registry of shared CmdletArg definitions used across multiple cmdlet."""
 
@@ -100,6 +144,13 @@ class SharedArgs:
         description="selects plugin",
     )
 
+    INSTANCE = CmdletArg(
+        name="instance",
+        type="string",
+        description="Selects a plugin instance",
+        query_key="instance",
+    )
+
     @staticmethod
     def get_store_choices(config: Optional[Dict[str, Any]] = None, force: bool = False) -> List[str]:
         if not force and hasattr(SharedArgs, "_cached_available_stores"):