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

vsc/output/errors.py

@@ -0,0 +1,106 @@
+"""Map SDK/transport exceptions to the stable error envelope + exit codes.
+
+vAPI errors are both ``Exception`` and ``VapiStruct``; dispatch on the stable
+``error_type`` string rather than ``isinstance`` chains. Transport-layer failures
+(``requests`` connection/TLS errors) happen before the vAPI layer and are mapped
+separately.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import com.vmware.vapi.std.errors_client as verr
+
+from vsc.output.exit_codes import ExitCode
+
+# vAPI ``error_type`` -> exit code. Unlisted/None -> ExitCode.ERROR.
+ERROR_TYPE_TO_EXIT: dict[str, ExitCode] = {
+    "UNAUTHENTICATED": ExitCode.AUTH,
+    "UNAUTHORIZED": ExitCode.AUTH,
+    "INVALID_ARGUMENT": ExitCode.USAGE,
+    "UNSUPPORTED": ExitCode.USAGE,
+    "UNEXPECTED_INPUT": ExitCode.USAGE,
+    "OPERATION_NOT_FOUND": ExitCode.USAGE,
+    "NOT_FOUND": ExitCode.NOT_FOUND,
+    "RESOURCE_INACCESSIBLE": ExitCode.NOT_FOUND,
+    "ALREADY_EXISTS": ExitCode.CONFLICT,
+    "ALREADY_IN_DESIRED_STATE": ExitCode.CONFLICT,
+    "RESOURCE_IN_USE": ExitCode.CONFLICT,
+    "FEATURE_IN_USE": ExitCode.CONFLICT,
+    "NOT_ALLOWED_IN_CURRENT_STATE": ExitCode.CONFLICT,
+    "CONCURRENT_CHANGE": ExitCode.CONFLICT,
+    "SERVICE_UNAVAILABLE": ExitCode.UNAVAILABLE,
+    "RESOURCE_BUSY": ExitCode.UNAVAILABLE,
+    "TIMED_OUT": ExitCode.UNAVAILABLE,
+    "UNABLE_TO_ALLOCATE_RESOURCE": ExitCode.UNAVAILABLE,
+    "INTERNAL_SERVER_ERROR": ExitCode.ERROR,
+    "CANCELED": ExitCode.ERROR,
+}
+
+
+def _messages(err: Any) -> str:
+    msgs = getattr(err, "messages", None) or []
+    texts = [getattr(m, "default_message", None) for m in msgs]
+    joined = "; ".join(t for t in texts if t)
+    return joined or str(err) or err.__class__.__name__
+
+
+def envelope_for_vapi(err: Any) -> tuple[dict[str, Any], ExitCode]:
+    """Build the error envelope + exit code for a vAPI error."""
+    error_type = getattr(err, "error_type", None)
+    code = ERROR_TYPE_TO_EXIT.get(error_type or "", ExitCode.ERROR)
+    detail: Any
+    try:
+        detail = err.to_dict()
+    except Exception:
+        detail = None
+    env = {
+        "error": {
+            "code": int(code),
+            "kind": error_type or err.__class__.__name__,
+            "message": _messages(err),
+            "details": detail,
+        }
+    }
+    return env, code
+
+
+def envelope_for_transport(err: Exception) -> tuple[dict[str, Any], ExitCode]:
+    """Build the error envelope + exit code for a transport-layer error.
+
+    TLS trust failures are a *connection* problem (failure to negotiate), not an
+    authentication failure — they get :class:`ExitCode.CONNECTION` plus a hint
+    pointing at the ``VSC_<BACKEND>_INSECURE`` escape hatch.
+    """
+    name = err.__class__.__name__
+    message = str(err) or name
+    if "SSL" in name:
+        message = (
+            f"TLS verification failed: {message} "
+            "(for a self-signed/lab cert, set VSC_<BACKEND>_INSECURE=1)"
+        )
+    env = {
+        "error": {
+            "code": int(ExitCode.CONNECTION),
+            "kind": name,
+            "message": message,
+            "details": None,
+        }
+    }
+    return env, ExitCode.CONNECTION
+
+
+def render_error(env: dict[str, Any], fmt: str) -> None:
+    """Print the error envelope to stderr (JSON always; ``message`` for tables)."""
+    if fmt == "table":
+        print(env["error"]["message"], file=sys.stderr)
+    else:
+        print(json.dumps(env, default=str), file=sys.stderr)
+
+
+def is_vapi_error(err: BaseException) -> bool:
+    """True if ``err`` is a vAPI ``Error`` (has the stable ``error_type``)."""
+    return isinstance(err, verr.Error)

vsc/output/exit_codes.py

@@ -0,0 +1,40 @@
+"""Documented, stable process exit codes.
+
+These are part of the CLI's public contract for scripts and agents. Values are
+frozen; add new codes rather than renumbering existing ones.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    """Stable exit codes returned by ``vsc``."""
+
+    OK = 0
+    """Success."""
+
+    ERROR = 1
+    """Generic/unexpected failure."""
+
+    USAGE = 2
+    """Invalid arguments or usage (Typer/Click default)."""
+
+    AUTH = 3
+    """Authentication or authorization failure."""
+
+    NOT_FOUND = 4
+    """A requested resource does not exist."""
+
+    CONNECTION = 5
+    """Could not reach or negotiate with the target (vCenter/NSX)."""
+
+    CONFIG = 6
+    """Missing or invalid configuration/profile."""
+
+    CONFLICT = 7
+    """Resource conflict (already exists, in use, wrong state, concurrent change)."""
+
+    UNAVAILABLE = 8
+    """Target temporarily unavailable, busy, or the request timed out."""

vsc/output/render.py

@@ -0,0 +1,134 @@
+"""Render SDK results to JSON (default) or a Rich table.
+
+vAPI results are ``VapiStruct`` instances (or lists/maps of them). ``to_dict()``
+parses floats as ``Decimal``, so JSON serialization uses ``default=str``. Dict
+keys are wire/canonical names (e.g. ``memory_size_MiB``), not the snake_case
+constructor kwargs — we surface them as-is.
+"""
+
+from __future__ import annotations
+
+import enum
+import json
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+from vmware.vapi.bindings.struct import VapiStruct
+
+
+class OutputFormat(str, enum.Enum):
+    """Supported ``--output`` formats."""
+
+    json = "json"
+    table = "table"
+
+
+def jsonable(value: Any) -> Any:
+    """Convert a vAPI result into a JSON-serializable structure."""
+    if isinstance(value, VapiStruct):
+        return {k: jsonable(v) for k, v in value.to_dict().items()}
+    if isinstance(value, enum.Enum):
+        return value.value
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [jsonable(v) for v in value]
+    if isinstance(value, dict):
+        return {str(k): jsonable(v) for k, v in value.items()}
+    return value
+
+
+def to_json(value: Any) -> str:
+    """Serialize a result to indented JSON text."""
+    return json.dumps(jsonable(value), indent=2, default=str, sort_keys=False)
+
+
+def _rows(data: Any) -> list[dict[str, Any]]:
+    if isinstance(data, dict):
+        return [data]
+    if isinstance(data, list):
+        return [r for r in data if isinstance(r, dict)]
+    return []
+
+
+def to_table(value: Any, console: Console) -> bool:
+    """Render ``value`` as a Rich table. Returns ``False`` if it isn't tabular."""
+    data = jsonable(value)
+    rows = _rows(data)
+    if not rows:
+        return False
+    columns: list[str] = []
+    for row in rows:
+        for key in row:
+            if key not in columns:
+                columns.append(key)
+    table = Table(show_header=True, header_style="bold")
+    for col in columns:
+        table.add_column(col)
+    for row in rows:
+        table.add_row(*[_cell(row.get(col)) for col in columns])
+    console.print(table)
+    return True
+
+
+def _cell(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, default=str)
+    return str(value)
+
+
+def emit(value: Any, fmt: str | OutputFormat = "json", *, console: Console | None = None) -> None:
+    """Print a result in the requested format (``json`` or ``table``)."""
+    fmt = fmt.value if isinstance(fmt, OutputFormat) else fmt
+    if fmt == "table":
+        console = console or Console()
+        if to_table(value, console):
+            return
+        # Fall back to JSON for non-tabular payloads (e.g. a single scalar).
+    print(to_json(value))
+
+
+_APPLY_HINT = "re-run with --apply to execute"
+
+
+def write_envelope(plan: dict[str, Any], *, applied: bool, result: Any = None) -> dict[str, Any]:
+    """Build the stable write envelope shared by dry-run and apply.
+
+    Dry-run (``applied=False``) carries the plan and an apply hint and never a
+    result; apply (``applied=True``) carries the plan and the SDK response.
+    """
+    env: dict[str, Any] = {"applied": applied, "request": plan}
+    if applied:
+        env["result"] = jsonable(result)
+    else:
+        env["apply_hint"] = _APPLY_HINT
+    return env
+
+
+def emit_request(
+    plan: dict[str, Any],
+    *,
+    applied: bool,
+    result: Any = None,
+    fmt: str | OutputFormat = "json",
+    console: Console | None = None,
+) -> None:
+    """Print the write envelope (dry-run preview or applied result)."""
+    fmt = fmt.value if isinstance(fmt, OutputFormat) else fmt
+    env = write_envelope(plan, applied=applied, result=result)
+    if fmt == "table":
+        console = console or Console()
+        status = "APPLIED" if applied else "DRY-RUN"
+        console.print(f"[bold]{status}[/bold] {plan['method']} {plan['url']}")
+        if not applied:
+            console.print(f"({_APPLY_HINT})")
+            return
+        # Applied: show the result as a table, or a clean scalar/empty line — never
+        # fall through to dumping the whole JSON envelope in table mode.
+        if result is None:
+            console.print("(no body)")
+        elif not to_table(result, console):
+            console.print(to_json(result))
+        return
+    print(to_json(env))

vsc/skill/__init__.py

@@ -0,0 +1 @@
+"""The bundled agent Skill and its export command."""

vsc/skill/assets/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: vcf-super-cli
+description: Use when querying or changing VMware Cloud Foundation 9 (vSphere/vCenter and NSX Policy) from the command line via `vsc`. The command tree is generated from the vcf-sdk. Reads return JSON; writes are dry-run by default and require `--apply`.
+---
+
+# vcf-super-cli (`vsc`)
+
+`vsc` is a CLI for VMware Cloud Foundation 9. Its command tree is generated from
+the `vcf-sdk` vAPI bindings and split into two product groups:
+
+- `vsc vsphere …` — vCenter (vm, host, cluster, datacenter, datastore, folder, network,
+  resource-pool, and the VM power/hardware leaves: power, cpu, memory, disk, ethernet —
+  each takes the VM id as an argument, e.g. `vsc vsphere power stop <vm>`)
+- `vsc nsx …` — NSX Policy (segments, tier0s, tier1s, services, groups, security-policies,
+  gateway-policies, ip-pools, dhcp-server-configs, dhcp-relay-configs, locale-services)
+
+Discover the live surface with `vsc --help`, `vsc vsphere --help`, `vsc nsx --help`,
+and `vsc vsphere vm --help`. Leaves expose `list`/`get <id>` reads and — where the SDK
+provides them — write verbs (`create`, `delete`, `set`, `patch`, power actions, …).
+
+## Writes are dry-run by default
+
+**Every write command previews and changes nothing unless you pass `--apply`.** This is
+the core safety contract — a write without `--apply` never opens a connection.
+
+```sh
+vsc --profile prod vsphere vm delete vm-42            # DRY-RUN: prints the plan, changes nothing
+vsc --profile prod vsphere vm delete vm-42 --apply    # executes the delete
+```
+
+Dry-run emits the resolved request so you can see exactly what `--apply` would send:
+
+```json
+{ "applied": false,
+  "request": { "method": "DELETE", "url": "/vcenter/vm/vm-42",
+               "path_params": {"vm": "vm-42"}, "query": {}, "body": null,
+               "backend": "vsphere", "service": "vm", "operation": "delete" },
+  "apply_hint": "re-run with --apply to execute" }
+```
+
+With `--apply`, the same envelope carries `"applied": true` and a `"result"` field
+(the SDK response) instead of `apply_hint`. Branch on `applied`.
+
+Bodies/specs are passed as JSON to the relevant option and built into the SDK struct:
+
+```sh
+vsc --profile prod nsx segments set web --segment '{"display_name":"web"}'            # dry-run
+vsc --profile prod nsx segments set web --segment '{"display_name":"web"}' --apply    # executes
+```
+
+Write failures use the same error envelope + exit codes — notably `7` CONFLICT
+(already-exists / in-use / wrong-state / concurrent-change) and `8` UNAVAILABLE
+(busy / timed-out / temporarily unavailable).
+
+## Conventions for agents
+
+- **Output is JSON by default** — parse `stdout`. Use `--output table` / `-o table`
+  only for human display.
+- **Errors** go to `stderr` as `{ "error": { "code", "kind", "message", "details" } }`.
+  `stdout` is data only; logs/diagnostics go to `stderr`.
+- **Exit codes** are stable — branch on these, not on message text:
+  `0` ok · `1` generic · `2` usage · `3` auth · `4` not-found · `5` connection ·
+  `6` config · `7` conflict · `8` unavailable.
+
+## Targeting an environment
+
+Configure once, then select per command with `--profile/-p`:
+
+```sh
+vsc profiles add prod --vsphere-server vc.example --vsphere-username administrator@vsphere.local
+vsc profiles set-password prod vsphere          # prompts; stored in the OS keyring
+vsc --profile prod vsphere vm list
+```
+
+Environment variables override the profile (useful in CI):
+`VSC_VSPHERE_SERVER`, `VSC_VSPHERE_USERNAME`, `VSC_VSPHERE_PASSWORD`,
+`VSC_VSPHERE_INSECURE`, and the `VSC_NSX_*` equivalents; `VSC_PROFILE` selects a profile.
+
+## Examples
+
+```sh
+# Reads
+vsc --profile prod vsphere vm list
+vsc --profile prod vsphere vm get vm-42
+vsc --profile prod vsphere host list -o table
+vsc --profile prod nsx segments list
+vsc --profile prod nsx tier1s get <tier1-id>
+
+# Writes — preview first (dry-run), then --apply
+vsc --profile prod vsphere power stop vm-42                    # preview
+vsc --profile prod vsphere power stop vm-42 --apply            # execute
+vsc --profile prod nsx tier1s set t1-web --tier1 '{"display_name":"web"}' --apply
+```
+
+> This Skill ships with the package. Refresh an exported copy with
+> `vsc skill export <dir> --apply`.

vsc/skill/export.py

@@ -0,0 +1,26 @@
+"""Read the bundled agent Skill and export it to a directory."""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path
+
+_SKILL_NAME = "vcf-super-cli"
+
+
+def skill_text() -> str:
+    """Return the bundled SKILL.md content."""
+    return (files("vsc.skill") / "assets" / "SKILL.md").read_text(encoding="utf-8")
+
+
+def export_path(dest_dir: Path) -> Path:
+    """The file that :func:`export_skill` would write under ``dest_dir``."""
+    return dest_dir / _SKILL_NAME / "SKILL.md"
+
+
+def export_skill(dest_dir: Path) -> Path:
+    """Write the bundled SKILL.md to ``dest_dir/vcf-super-cli/SKILL.md``."""
+    target = export_path(dest_dir)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(skill_text(), encoding="utf-8")
+    return target