jkj

cmdlet_catalog.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any, Dict, List, Optional
+
+try:
+    from cmdlet import REGISTRY
+except Exception:
+    REGISTRY = {}  # type: ignore
+
+try:
+    from cmdnat import register_native_commands as _register_native_commands
+except Exception:
+    _register_native_commands = None
+
+
+def ensure_registry_loaded() -> None:
+    """Ensure native commands are registered into REGISTRY (idempotent)."""
+    if _register_native_commands and REGISTRY is not None:
+        try:
+            _register_native_commands(REGISTRY)
+        except Exception:
+            pass
+
+
+def _normalize_mod_name(mod_name: str) -> str:
+    """Normalize a command/module name for import resolution."""
+    normalized = (mod_name or "").strip()
+    if normalized.startswith("."):
+        normalized = normalized.lstrip(".")
+    normalized = normalized.replace("-", "_")
+    return normalized
+
+
+def import_cmd_module(mod_name: str):
+    """Import a cmdlet/native module from cmdnat or cmdlet packages."""
+    normalized = _normalize_mod_name(mod_name)
+    if not normalized:
+        return None
+    for package in ("cmdnat", "cmdlet", None):
+        try:
+            qualified = f"{package}.{normalized}" if package else normalized
+            return import_module(qualified)
+        except ModuleNotFoundError:
+            continue
+        except Exception:
+            continue
+    return None
+
+
+def _normalize_arg(arg: Any) -> Dict[str, Any]:
+    """Convert a CmdletArg/dict into a plain metadata dict."""
+    if isinstance(arg, dict):
+        name = arg.get("name", "")
+        return {
+            "name": str(name).lstrip("-"),
+            "type": arg.get("type", "string"),
+            "required": bool(arg.get("required", False)),
+            "description": arg.get("description", ""),
+            "choices": arg.get("choices", []) or [],
+            "alias": arg.get("alias", ""),
+            "variadic": arg.get("variadic", False),
+        }
+
+    name = getattr(arg, "name", "") or ""
+    return {
+        "name": str(name).lstrip("-"),
+        "type": getattr(arg, "type", "string"),
+        "required": bool(getattr(arg, "required", False)),
+        "description": getattr(arg, "description", ""),
+        "choices": getattr(arg, "choices", []) or [],
+        "alias": getattr(arg, "alias", ""),
+        "variadic": getattr(arg, "variadic", False),
+    }
+
+
+def get_cmdlet_metadata(cmd_name: str) -> Optional[Dict[str, Any]]:
+    """Return normalized metadata for a cmdlet, if available (aliases supported)."""
+    ensure_registry_loaded()
+    normalized = cmd_name.replace("-", "_")
+    mod = import_cmd_module(normalized)
+    data = getattr(mod, "CMDLET", None) if mod else None
+
+    if data is None:
+        try:
+            reg_fn = (REGISTRY or {}).get(cmd_name.replace("_", "-").lower())
+            if reg_fn:
+                owner_mod = getattr(reg_fn, "__module__", "")
+                if owner_mod:
+                    owner = import_module(owner_mod)
+                    data = getattr(owner, "CMDLET", None)
+        except Exception:
+            data = None
+
+    if not data:
+        return None
+
+    if hasattr(data, "to_dict"):
+        base = data.to_dict()
+    elif isinstance(data, dict):
+        base = data
+    else:
+        base = {}
+
+    name = getattr(data, "name", base.get("name", cmd_name)) or cmd_name
+    aliases = getattr(data, "alias", base.get("alias", [])) or []
+    usage = getattr(data, "usage", base.get("usage", ""))
+    summary = getattr(data, "summary", base.get("summary", ""))
+    details = getattr(data, "detail", base.get("detail", [])) or []
+    args_list = getattr(data, "arg", base.get("arg", [])) or []
+    args = [_normalize_arg(arg) for arg in args_list]
+
+    return {
+        "name": str(name).replace("_", "-").lower(),
+        "aliases": [str(a).replace("_", "-").lower() for a in aliases if a],
+        "usage": usage,
+        "summary": summary,
+        "details": details,
+        "args": args,
+        "raw": data,
+    }
+
+
+def list_cmdlet_metadata() -> Dict[str, Dict[str, Any]]:
+    """Collect metadata for all registered cmdlet keyed by canonical name."""
+    ensure_registry_loaded()
+    entries: Dict[str, Dict[str, Any]] = {}
+    for reg_name in (REGISTRY or {}).keys():
+        meta = get_cmdlet_metadata(reg_name)
+        canonical = str(reg_name).replace("_", "-").lower()
+
+        if meta:
+            canonical = meta.get("name", canonical)
+            aliases = meta.get("aliases", [])
+            base = entries.get(
+                canonical,
+                {
+                    "name": canonical,
+                    "aliases": [],
+                    "usage": "",
+                    "summary": "",
+                    "details": [],
+                    "args": [],
+                    "raw": meta.get("raw"),
+                },
+            )
+            merged_aliases = set(base.get("aliases", [])) | set(aliases)
+            if canonical != reg_name:
+                merged_aliases.add(reg_name)
+            base["aliases"] = sorted(a for a in merged_aliases if a and a != canonical)
+            if not base.get("usage") and meta.get("usage"):
+                base["usage"] = meta["usage"]
+            if not base.get("summary") and meta.get("summary"):
+                base["summary"] = meta["summary"]
+            if not base.get("details") and meta.get("details"):
+                base["details"] = meta["details"]
+            if not base.get("args") and meta.get("args"):
+                base["args"] = meta["args"]
+            if not base.get("raw"):
+                base["raw"] = meta.get("raw")
+            entries[canonical] = base
+        else:
+            entries.setdefault(
+                canonical,
+                {"name": canonical, "aliases": [], "usage": "", "summary": "", "details": [], "args": [], "raw": None},
+            )
+    return entries
+
+
+def list_cmdlet_names(include_aliases: bool = True) -> List[str]:
+    """Return sorted cmdlet names (optionally including aliases)."""
+    ensure_registry_loaded()
+    entries = list_cmdlet_metadata()
+    names = set()
+    for meta in entries.values():
+        names.add(meta.get("name", ""))
+        if include_aliases:
+            for alias in meta.get("aliases", []):
+                names.add(alias)
+    return sorted(n for n in names if n)
+
+
+def get_cmdlet_arg_flags(cmd_name: str) -> List[str]:
+    """Return flag variants for cmdlet arguments (e.g., -name/--name)."""
+    meta = get_cmdlet_metadata(cmd_name)
+    if not meta:
+        return []
+
+    flags: List[str] = []
+    seen: set[str] = set()
+
+    for arg in meta.get("args", []):
+        name = str(arg.get("name") or "").strip().lstrip("-")
+        if not name:
+            continue
+        for candidate in (f"-{name}", f"--{name}"):
+            if candidate not in seen:
+                flags.append(candidate)
+                seen.add(candidate)
+
+    return flags
+
+
+def get_cmdlet_arg_choices(cmd_name: str, arg_name: str) -> List[str]:
+    """Return declared choices for a cmdlet argument."""
+    meta = get_cmdlet_metadata(cmd_name)
+    if not meta:
+        return []
+    target = arg_name.lstrip("-")
+    for arg in meta.get("args", []):
+        if arg.get("name") == target:
+            return list(arg.get("choices", []) or [])
+    return []