vcf-super-cli 0.2.0__py3-none-any.whl

vsc/cli/skill.py

@@ -0,0 +1,28 @@
+"""`vsc skill` commands: export the bundled agent Skill."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from vsc.output.render import to_json
+from vsc.skill.export import export_path, export_skill
+
+skill_app = typer.Typer(no_args_is_help=True, help="The bundled agent Skill.")
+
+
+@skill_app.command("export")
+def export(
+    directory: Path = typer.Argument(..., help="Directory to export the Skill into."),
+    apply: bool = typer.Option(
+        False, "--apply", help="Actually write the file (otherwise dry-run prints the path)."
+    ),
+) -> None:
+    """Export the bundled SKILL.md to ``<directory>/vcf-super-cli/SKILL.md``."""
+    target = export_path(directory)
+    if not apply:
+        print(to_json({"dry_run": True, "would_write": str(target)}))
+        return
+    written = export_skill(directory)
+    print(to_json({"written": str(written)}))

vsc/config/__init__.py

@@ -0,0 +1,7 @@
+"""Named profiles and configuration for ``vsc``.
+
+A profile bundles per-backend connection details (server, username, optional
+password, TLS verification). Profiles live in a YAML file under the platform
+config dir; passwords are kept in the OS keyring by default. Environment
+variables (``VSC_*``) always override the stored profile.
+"""

vsc/config/schema.py

@@ -0,0 +1,39 @@
+"""Pydantic models for the on-disk configuration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+BACKENDS = ("vsphere", "nsx")
+
+
+class BackendCreds(BaseModel):
+    """Connection details for one backend within a profile."""
+
+    server: str
+    username: str
+    password: str | None = None  # None => look in the OS keyring
+    insecure: bool = False
+
+    model_config = {"extra": "forbid"}
+
+
+class Profile(BaseModel):
+    """A named target environment (a vCenter and/or an NSX manager)."""
+
+    vsphere: BackendCreds | None = None
+    nsx: BackendCreds | None = None
+
+    model_config = {"extra": "forbid"}
+
+    def backend(self, name: str) -> BackendCreds | None:
+        return getattr(self, name, None)
+
+
+class Config(BaseModel):
+    """The whole configuration file."""
+
+    current_profile: str | None = None
+    profiles: dict[str, Profile] = Field(default_factory=dict)
+
+    model_config = {"extra": "forbid"}

vsc/config/store.py

@@ -0,0 +1,105 @@
+"""Load/save the config file and broker passwords through the OS keyring."""
+
+from __future__ import annotations
+
+import io
+import os
+from pathlib import Path
+
+import keyring
+import platformdirs
+import structlog
+from pydantic import ValidationError
+from ruamel.yaml import YAML
+from ruamel.yaml.error import YAMLError
+
+from vsc.config.schema import Config
+
+log = structlog.get_logger(__name__)
+
+_KEYRING_SERVICE = "vcf-super-cli"
+_yaml = YAML(typ="safe")
+_yaml.default_flow_style = False
+
+
+class ConfigError(Exception):
+    """The configuration file exists but is malformed or invalid."""
+
+
+def config_path() -> Path:
+    """Location of the config file (``VSC_CONFIG_FILE`` overrides the default)."""
+    override = os.environ.get("VSC_CONFIG_FILE")
+    if override:
+        return Path(override)
+    return Path(platformdirs.user_config_dir("vcf-super-cli", appauthor=False)) / "config.yaml"
+
+
+def load_config() -> Config:
+    """Read the config file, returning an empty Config if it does not exist.
+
+    Raises :class:`ConfigError` (never a raw parse/validation error) if the file
+    exists but is malformed, so callers can map it to a clean exit code.
+    """
+    path = config_path()
+    if not path.exists():
+        return Config()
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            data = _yaml.load(fh) or {}
+        return Config.model_validate(data)
+    except (YAMLError, ValidationError, TypeError) as exc:
+        raise ConfigError(f"invalid config at {path}: {exc}") from exc
+
+
+def save_config(config: Config) -> Path:
+    """Atomically write the config file at mode 0600 and return its path.
+
+    The file is created with 0600 from the start (never a looser intermediate
+    mode) and swapped in via an atomic rename, so a cleartext password is never
+    momentarily world/group-readable.
+    """
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.parent.chmod(0o700)
+    data = config.model_dump(exclude_none=True)
+    buffer = io.StringIO()
+    _yaml.dump(data, buffer)
+
+    tmp = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        os.write(fd, buffer.getvalue().encode("utf-8"))
+    finally:
+        os.close(fd)
+    os.replace(tmp, path)
+    path.chmod(0o600)
+    return path
+
+
+# --------------------------------------------------------------------------- #
+# Keyring (best-effort; a missing backend degrades gracefully)
+# --------------------------------------------------------------------------- #
+
+
+def keyring_get(profile: str, backend: str) -> str | None:
+    try:
+        return keyring.get_password(_KEYRING_SERVICE, f"{profile}:{backend}")
+    except Exception as exc:
+        log.debug("keyring.get_failed", error=str(exc))
+        return None
+
+
+def keyring_set(profile: str, backend: str, password: str) -> bool:
+    try:
+        keyring.set_password(_KEYRING_SERVICE, f"{profile}:{backend}", password)
+        return True
+    except Exception as exc:
+        log.debug("keyring.set_failed", error=str(exc))
+        return False
+
+
+def keyring_delete(profile: str, backend: str) -> None:
+    try:
+        keyring.delete_password(_KEYRING_SERVICE, f"{profile}:{backend}")
+    except Exception as exc:
+        log.debug("keyring.delete_failed", error=str(exc))

vsc/connect/__init__.py

@@ -0,0 +1,6 @@
+"""Connections, sessions, and authentication for vCenter and NSX.
+
+The generator is connection-agnostic: it asks a ``connect_for_backend`` callable
+for an authenticated ``StubConfiguration`` only when a command actually runs, so
+``--help`` and tree assembly stay fully offline.
+"""

vsc/connect/session.py

@@ -0,0 +1,73 @@
+"""Build authenticated vAPI ``StubConfiguration`` objects.
+
+vCenter uses session-id auth: username/password is exchanged for a session id
+(one network round-trip), then every call carries that session. NSX uses HTTP
+basic auth applied per request — no session to create or delete.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import requests
+import urllib3
+from com.vmware.cis_client import Session
+from vmware.vapi.bindings.stub import StubConfiguration
+from vmware.vapi.lib.connect import get_requests_connector
+from vmware.vapi.security.client.security_context_filter import (
+    LegacySecurityContextFilter,
+)
+from vmware.vapi.security.session import create_session_security_context
+from vmware.vapi.security.user_password import (
+    create_user_password_security_context,
+)
+from vmware.vapi.stdlib.client.factories import StubConfigurationFactory
+
+
+def _session(verify: bool) -> requests.Session:
+    sess = requests.Session()
+    sess.verify = verify
+    if not verify:
+        urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+    return sess
+
+
+def connect_vsphere(
+    server: str, username: str, password: str, *, verify: bool = True
+) -> StubConfiguration:
+    """Authenticate to vCenter and return a session-backed StubConfiguration."""
+    sess = _session(verify)
+    url = f"https://{server}/api"
+    login_cfg = StubConfigurationFactory.new_std_configuration(
+        get_requests_connector(
+            session=sess,
+            url=url,
+            provider_filter_chain=[
+                LegacySecurityContextFilter(
+                    security_context=create_user_password_security_context(username, password)
+                )
+            ],
+        )
+    )
+    session_id: str = Session(login_cfg).create()
+    return StubConfigurationFactory.new_std_configuration(
+        get_requests_connector(
+            session=sess,
+            url=url,
+            provider_filter_chain=[
+                LegacySecurityContextFilter(
+                    security_context=create_session_security_context(session_id)
+                )
+            ],
+        )
+    )
+
+
+def connect_nsx(
+    server: str, username: str, password: str, *, verify: bool = True
+) -> StubConfiguration:
+    """Return a basic-auth StubConfiguration for the NSX Policy API."""
+    sess = _session(verify)
+    connector: Any = get_requests_connector(session=sess, url=f"https://{server}")
+    connector.set_security_context(create_user_password_security_context(username, password))
+    return StubConfiguration(connector)

vsc/connect/targets.py

@@ -0,0 +1,121 @@
+"""Resolve connection targets and hand out cached StubConfigurations.
+
+Resolution order for each field: the active profile (file + keyring), then
+environment-variable overrides (``VSC_<BACKEND>_*``), which always win. With no
+config file at all, pure env-var operation still works.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from vmware.vapi.bindings.stub import StubConfiguration
+
+from vsc.config.schema import BackendCreds
+from vsc.config.store import keyring_get, load_config
+from vsc.connect.session import connect_nsx, connect_vsphere
+
+_TRUTHY = {"1", "true", "yes", "on"}
+
+# Process-wide active profile override set by the global --profile option.
+# Held in a dict to avoid a module-level `global` statement.
+_state: dict[str, str | None] = {"profile": None}
+
+
+class TargetNotConfigured(Exception):
+    """A backend was invoked without the credentials needed to reach it."""
+
+
+@dataclass(frozen=True)
+class Target:
+    """Resolved connection details for one backend."""
+
+    server: str
+    username: str
+    password: str
+    verify: bool
+
+
+def set_active_profile(name: str | None) -> None:
+    """Set the profile selected via ``--profile`` for this process."""
+    _state["profile"] = name
+
+
+def active_profile_name() -> str | None:
+    """The effective profile name: --profile, then VSC_PROFILE, then config."""
+    if _state["profile"]:
+        return _state["profile"]
+    env = os.environ.get("VSC_PROFILE")
+    if env:
+        return env
+    return load_config().current_profile
+
+
+def _profile_creds(backend: str) -> tuple[BackendCreds | None, str | None]:
+    name = active_profile_name()
+    if not name:
+        return None, None
+    profile = load_config().profiles.get(name)
+    if profile is None:
+        return None, name
+    return profile.backend(backend), name
+
+
+def resolve_target(backend: str) -> Target:
+    """Resolve a :class:`Target` from profile + env overrides for ``backend``."""
+    creds, profile_name = _profile_creds(backend)
+    server = creds.server if creds else None
+    username = creds.username if creds else None
+    password = creds.password if creds else None
+    insecure = creds.insecure if creds else False
+    if creds and password is None and profile_name:
+        password = keyring_get(profile_name, backend)
+
+    prefix = f"VSC_{backend.upper()}"
+    server = os.environ.get(f"{prefix}_SERVER", server or "") or None
+    username = os.environ.get(f"{prefix}_USERNAME", username or "") or None
+    password = os.environ.get(f"{prefix}_PASSWORD", password or "") or None
+    env_insecure = os.environ.get(f"{prefix}_INSECURE")
+    if env_insecure:  # non-empty only; an empty string is not an override
+        insecure = env_insecure.strip().lower() in _TRUTHY
+
+    missing = [
+        field
+        for field, val in (("server", server), ("username", username), ("password", password))
+        if not val
+    ]
+    if missing:
+        hint = (
+            f"profile {active_profile_name()!r}" if active_profile_name() else "no active profile"
+        )
+        raise TargetNotConfigured(
+            f"{backend}: missing {', '.join(missing)} ({hint}; "
+            f"set {prefix}_* env vars or run `vsc profiles add`)"
+        )
+    assert server and username and password
+    return Target(server=server, username=username, password=password, verify=not insecure)
+
+
+_CACHE: dict[str, StubConfiguration] = {}
+
+
+def connect_for_backend(backend: str) -> StubConfiguration:
+    """Return an authenticated StubConfiguration for ``backend`` (cached)."""
+    cached = _CACHE.get(backend)
+    if cached is not None:
+        return cached
+    target = resolve_target(backend)
+    if backend == "vsphere":
+        cfg = connect_vsphere(target.server, target.username, target.password, verify=target.verify)
+    elif backend == "nsx":
+        cfg = connect_nsx(target.server, target.username, target.password, verify=target.verify)
+    else:  # pragma: no cover - guarded by the generator's backend values
+        raise TargetNotConfigured(f"unknown backend {backend!r}")
+    _CACHE[backend] = cfg
+    return cfg
+
+
+def reset_cache() -> None:
+    """Drop cached connections (used by tests and re-auth)."""
+    _CACHE.clear()

vsc/gen/__init__.py

@@ -0,0 +1,7 @@
+"""Command-tree generation from the vcf-sdk vAPI bindings.
+
+The generator introspects installed ``VapiInterface`` service classes (vCenter and
+NSX Policy), reads their embedded REST + type metadata, and assembles a Typer
+command tree. It runs fully offline — no server or credentials are needed to build
+``--help``.
+"""

vsc/gen/builder.py

@@ -0,0 +1,243 @@
+"""Turn :class:`Operation` objects into Typer commands and assemble the tree.
+
+Each generated command builds its own ``inspect.Signature`` so Typer can derive
+options/arguments dynamically. Connections are resolved lazily through an injected
+``connect_for_backend`` callable, keeping tree assembly and ``--help`` offline.
+"""
+
+from __future__ import annotations
+
+import inspect
+import keyword
+from collections.abc import Callable
+from typing import Any
+
+import requests
+import typer
+from vmware.vapi.exception import CoreException
+
+from vsc.config.store import ConfigError
+from vsc.connect.targets import TargetNotConfigured
+from vsc.gen.model import Operation, Param, ParamKind
+from vsc.gen.params import CoercionError, coerce_value
+from vsc.gen.preview import build_request_plan
+from vsc.output.errors import (
+    envelope_for_transport,
+    envelope_for_vapi,
+    is_vapi_error,
+    render_error,
+)
+from vsc.output.exit_codes import ExitCode
+from vsc.output.render import OutputFormat, emit, emit_request
+
+ConnectFn = Callable[[str], Any]
+
+_OUTPUT_PARAM = "_vsc_output"
+_APPLY_PARAM = "_vsc_apply"
+
+# User-facing option names the generator injects itself; a real SDK parameter with
+# one of these names is renamed so it can't shadow --output / --apply.
+_RESERVED_OPTION_NAMES = frozenset({"output", "apply"})
+
+_ANNOTATIONS: dict[ParamKind, type] = {
+    ParamKind.INTEGER: int,
+    ParamKind.DOUBLE: float,
+    ParamKind.BOOLEAN: bool,
+}
+
+
+def _annotation(param: Param) -> Any:
+    if param.kind in (ParamKind.LIST, ParamKind.SET):
+        base: Any = list[str]
+    else:
+        base = _ANNOTATIONS.get(param.kind, str)
+    return base if param.required else (base | None)
+
+
+def _help_text(param: Param) -> str:
+    bits: list[str] = [param.kind.value]
+    if param.kind is ParamKind.ENUM and param.enum_values:
+        bits.append("choices: " + ", ".join(param.enum_values))
+    if param.kind is ParamKind.ID and param.resource_types:
+        bits.append(f"id of {param.resource_types}")
+    if param.kind in (ParamKind.STRUCT, ParamKind.MAP, ParamKind.DYNAMIC):
+        bits.append("JSON")
+    return "; ".join(bits)
+
+
+def _sig_name(param: Param, used: set[str]) -> str:
+    name = param.name
+    reserved = name in (_OUTPUT_PARAM, _APPLY_PARAM) or name in _RESERVED_OPTION_NAMES
+    if keyword.iskeyword(name) or reserved or name in used:
+        name = f"{name}_"
+    used.add(name)
+    return name
+
+
+def _build_signature(op: Operation) -> tuple[inspect.Signature, list[tuple[Param, str]]]:
+    parameters: list[inspect.Parameter] = []
+    spec: list[tuple[Param, str]] = []
+    used: set[str] = set()
+    # Stable order: required path args first, then everything else.
+    ordered = sorted(op.params, key=lambda p: (not (p.in_path and p.required), p.name))
+    for param in ordered:
+        sig_name = _sig_name(param, used)
+        help_text = _help_text(param)
+        default: Any
+        if param.in_path:
+            default = typer.Argument(... if param.required else None, help=help_text)
+        else:
+            # A param named output/apply would otherwise emit --output/--apply and
+            # clash with the injected options; use the suffixed sig name for those.
+            opt_source = sig_name if param.name in _RESERVED_OPTION_NAMES else param.name
+            kebab = opt_source.replace("_", "-")
+            # Boolean options need a dual flag so the user can send False, not
+            # just True; otherwise only the positive flag exists.
+            opt = f"--{kebab}/--no-{kebab}" if param.kind is ParamKind.BOOLEAN else f"--{kebab}"
+            default = typer.Option(
+                ... if param.required else None,
+                opt,
+                help=help_text,
+                hide_input=param.kind is ParamKind.SECRET,
+            )
+        parameters.append(
+            inspect.Parameter(
+                sig_name,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                default=default,
+                annotation=_annotation(param),
+            )
+        )
+        spec.append((param, sig_name))
+    parameters.append(
+        inspect.Parameter(
+            _OUTPUT_PARAM,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            default=typer.Option(OutputFormat.json, "--output", "-o", help="Output format."),
+            annotation=OutputFormat,
+        )
+    )
+    if op.is_write:
+        # Writes preview by default; --apply opts in to actually executing.
+        parameters.append(
+            inspect.Parameter(
+                _APPLY_PARAM,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                default=typer.Option(
+                    False, "--apply/--no-apply", help="Execute the change (default: dry-run)."
+                ),
+                annotation=bool,
+            )
+        )
+    return inspect.Signature(parameters), spec
+
+
+def make_command(op: Operation, connect_fn: ConnectFn) -> Callable[..., None]:
+    """Build a Typer-compatible callback for ``op``."""
+    signature, spec = _build_signature(op)
+
+    def command(**kwargs: Any) -> None:
+        raw_fmt = kwargs.get(_OUTPUT_PARAM, OutputFormat.json)
+        fmt = raw_fmt.value if isinstance(raw_fmt, OutputFormat) else str(raw_fmt)
+        apply = bool(kwargs.get(_APPLY_PARAM, False))
+        # Coerce inputs and resolve the write plan up front. Building the plan
+        # serializes the request body, so a malformed/incomplete struct surfaces
+        # here as a clean usage error (exit 2) — before any connection — rather
+        # than leaking a vAPI traceback. CoreException is the SDK's client-side
+        # validation/serialization error.
+        try:
+            sdk_kwargs = _collect_kwargs(spec, kwargs)
+            plan = build_request_plan(op, sdk_kwargs) if op.is_write else None
+        except (CoercionError, CoreException) as exc:
+            _fail_usage(exc, fmt)
+            return
+        # Dry-run by default: preview the resolved request and touch nothing — no
+        # connection is opened unless the write is explicitly applied.
+        if op.is_write and not apply:
+            assert plan is not None  # guaranteed: op.is_write -> plan built above
+            emit_request(plan, applied=False, fmt=fmt)
+            return
+        try:
+            cfg = connect_fn(op.backend)
+            service = op.service_cls(cfg)
+            method = getattr(service, op.method_name, None)
+            if callable(method):
+                result = method(**sdk_kwargs)
+            else:
+                result = service._invoke(op.op_id, sdk_kwargs)
+            if op.is_write:
+                assert plan is not None  # guaranteed: op.is_write -> plan built above
+                emit_request(plan, applied=True, result=result, fmt=fmt)
+            else:
+                emit(result, fmt)
+        except TargetNotConfigured as exc:
+            _fail_config(exc, fmt)
+        except ConfigError as exc:
+            _fail(ExitCode.CONFIG, "ConfigError", exc, fmt)
+        except requests.exceptions.RequestException as exc:
+            env, code = envelope_for_transport(exc)
+            render_error(env, fmt)
+            raise typer.Exit(int(code)) from exc
+        except Exception as exc:
+            if not is_vapi_error(exc):
+                raise
+            env, code = envelope_for_vapi(exc)
+            render_error(env, fmt)
+            raise typer.Exit(int(code)) from exc
+
+    command.__signature__ = signature  # type: ignore[attr-defined]
+    command.__name__ = op.cli_verb.replace("-", "_")
+    command.__doc__ = f"{op.http_method} {op.url_template}"
+    return command
+
+
+def _collect_kwargs(spec: list[tuple[Param, str]], kwargs: dict[str, Any]) -> dict[str, Any]:
+    sdk_kwargs: dict[str, Any] = {}
+    for param, sig_name in spec:
+        value = kwargs.get(sig_name)
+        if value is None:
+            continue
+        if param.kind is ParamKind.ENUM and param.enum_values and value not in param.enum_values:
+            raise CoercionError(
+                f"{param.name!r}: {value!r} not in {{{', '.join(param.enum_values)}}}"
+            )
+        sdk_kwargs[param.name] = coerce_value(param, value)
+    return sdk_kwargs
+
+
+def _fail(code: ExitCode, kind: str, exc: Exception, fmt: str) -> None:
+    env = {"error": {"code": int(code), "kind": kind, "message": str(exc), "details": None}}
+    render_error(env, fmt)
+    raise typer.Exit(int(code)) from exc
+
+
+def _fail_config(exc: Exception, fmt: str) -> None:
+    _fail(ExitCode.CONFIG, "TargetNotConfigured", exc, fmt)
+
+
+def _fail_usage(exc: Exception, fmt: str) -> None:
+    _fail(ExitCode.USAGE, "InvalidArgument", exc, fmt)
+
+
+def build_group(operations: list[Operation], connect_fn: ConnectFn) -> typer.Typer:
+    """Assemble operations for one backend into a Typer app of service groups."""
+    services: dict[str, typer.Typer] = {}
+    used_names: dict[str, set[str]] = {}
+    for op in operations:
+        short = op.service_short.replace("_", "-")
+        group = services.get(short)
+        if group is None:
+            group = typer.Typer(no_args_is_help=True, help=f"{short} operations.")
+            services[short] = group
+            used_names[short] = set()
+        name = op.cli_verb
+        if name in used_names[short]:
+            name = op.op_id.replace("_", "-").replace("$", "-")
+        used_names[short].add(name)
+        group.command(name, help=f"{op.http_method} {op.url_template}")(
+            make_command(op, connect_fn)
+        )
+    root = typer.Typer(no_args_is_help=True)
+    for short, group in sorted(services.items()):
+        root.add_typer(group, name=short)
+    return root