vcf-super-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{vcf_super_cli-0.3.0 → vcf_super_cli-0.4.0}/CHANGELOG.md

@@ -7,6 +7,35 @@ versions may include breaking changes.
 
 ## [Unreleased]
 
+## v0.4.0 — 2026-06-08
+
+Live resource-id completion. Pressing `<TAB>` on an id-typed argument can now
+suggest **real ids** from the live inventory — strictly opt-in, cached, and
+fail-soft. The agent-facing contract is unchanged: stable JSON, error envelope,
+exit codes, dry-run-by-default writes, and `--help` stays fully offline.
+
+### Added
+
+- **Live resource-id completion** (#44), opt-in via `VSC_COMPLETE_DYNAMIC=1` and
+  off by default. When enabled, `<TAB>` on an id arg/option suggests live ids for
+  the resource type (VMs, hosts, clusters, datacenters, datastores, resource
+  pools), with each resource's name shown as completion help. Built on:
+  - a resource-type → list-op **registry** derived purely by introspecting the
+    SDK metadata (#45), no network;
+  - a **TTL cache** under the platform cache dir, keyed by
+    profile/backend/resource-type (default 60s, `VSC_COMPLETE_TTL` override) (#46);
+  - a **dynamic completer** whose fetch is time-bounded (`VSC_COMPLETE_TIMEOUT`,
+    default 2s) and blanket fail-soft — any error, missing auth, or timeout
+    yields no suggestions and is never cached (#47).
+- Static/offline completion (enums, output formats, profiles, filter enums) is
+  unchanged and remains the default. `--help` and command execution never open a
+  connection for completion.
+
+### Notes
+
+- Live completion is a human convenience only; agents should keep using `list`
+  to discover ids and must not depend on completion for correctness (#48).
+
 ## v0.3.0 — 2026-06-05
 
 Ergonomics: friendlier filtering and paging, offline shell completion, and a

{vcf_super_cli-0.3.0 → vcf_super_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vcf-super-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Modern, agent-friendly CLI for VMware Cloud Foundation 9, with a command tree generated dynamically from the vcf-sdk vAPI bindings.
 Project-URL: Homepage, https://github.com/thomaschristory/vcf-super-cli
 Project-URL: Documentation, https://thomaschristory.github.io/vcf-super-cli/

vcf_super_cli-0.4.0/docs/design.md

@@ -0,0 +1,89 @@
+# Design
+
+`vsc` builds its command tree by **statically introspecting the installed
+`vcf-sdk` vAPI bindings**. Both `vmware-vcenter` and `vcf-nsx` are vAPI stub
+libraries on the shared `vmware-vapi-runtime`:
+
+- Each service is a `VapiInterface` subclass (`VM`, `Host`, `Cluster`,
+  `Datastore`, `Network`, …).
+- Every operation carries `OperationRestMetadata` (`http_method`,
+  `path_variables`, `query_parameters`).
+- Parameters are typed via `StructType` binding types.
+
+A single generator walks those classes and emits one Typer command per
+operation. `http_method == "GET"` ⇒ a read command; other verbs ⇒ writes
+(dry-run by default + `--apply`). Because the metadata ships inside the SDK, the
+tree builds **offline** — no server needed to render `--help`.
+
+Top-level grouping:
+
+- `vsc vsphere …` → `com.vmware.vcenter` (+ selected `com.vmware.esx`)
+- `vsc nsx …` → `vcf.nsx.policy` (NSX Policy API)
+
+The introspected intermediate representation is a list of `Operation` objects,
+each carrying typed `Param`s (`vsc/gen/model.py`). Everything below is built from
+that one model.
+
+## Ergonomics (v0.3)
+
+These build on the introspected `Param` model without changing the agent
+contract.
+
+### Offline shell completion
+
+Completion values come entirely from the model and local config — **never a
+network call**, so `<TAB>` stays fast and `--help` stays offline. Enum options
+complete from their fixed choices, `--output` from the output formats, and
+`--profile` from configured profile names (`vsc/gen/complete.py`). Completing a
+live resource id would require a connection and is deferred to a later release.
+
+### Per-field filter flags
+
+A `list` operation takes a single `filter` parameter that is a struct
+(`VM.FilterSpec` etc.). The generator flattens that struct into typed
+`--<field>` options (repeatable for list/set fields; enum fields validate and
+complete their choices). The raw `--filter '<json>'` blob remains as a base
+layer that per-field flags merge **over** (`vsc/gen/filters.py`).
+
+### Pagination
+
+`list` commands gain `--all` (follow the NSX cursor across pages), `--max-items`
+(cap the total), and `--limit` (client-side cap for non-paginated vSphere
+lists). Without `--all`, a paginated list returns one page and surfaces its
+`cursor` for manual paging; on non-cursor backends `--all` is a no-op and the
+output stays a plain array (`vsc/gen/paginate.py`).
+
+## pyVmomi fallback (v0.3)
+
+A few inventory/performance areas are only reachable through the older pyVmomi
+SOAP API. Those are **hand-written read-only commands** mounted under
+`vsc vsphere` alongside the generated ones, sharing the same output contract:
+
+- a separate connection path, `connect_vmomi()` via `SmartConnect`, reusing the
+  resolved vSphere credentials and honouring `--insecure` like the REST path
+  (`vsc/connect/vmomi.py`);
+- `vmomi_jsonable()` collapses managed objects to their moref and data objects to
+  dicts so results render like any other;
+- a shared `run_read()` runner maps pyVmomi faults onto the same error envelope
+  and exit codes (`vsc/pyvmomi/runner.py`).
+
+Commands: `perf` (PerformanceManager counters), `events` / `tasks`
+(Event/Task managers), and `inventory` (a PropertyCollector property walk). All
+are reads — no `--apply`.
+
+## Design specs
+
+The authoritative, milestone-by-milestone designs live in the repository:
+
+- [v0.1 — dynamic read-only CLI](https://github.com/thomaschristory/vcf-super-cli/blob/main/docs/superpowers/specs/2026-06-05-vcf-super-cli-design.md)
+- [v0.2 — writes](https://github.com/thomaschristory/vcf-super-cli/blob/main/docs/superpowers/specs/2026-06-05-vcf-super-cli-v0.2-writes-design.md)
+- [v0.3 — ergonomics](https://github.com/thomaschristory/vcf-super-cli/blob/main/docs/superpowers/specs/2026-06-05-vcf-super-cli-v0.3-ergonomics-design.md)
+
+## Contracts
+
+- **Output:** JSON by default; `--output table` for humans.
+- **Errors:** stable envelope `{ "error": { code, message, kind, details } }`.
+- **Exit codes:** documented `IntEnum` (`0` ok, `1` generic, `2` usage, `3` auth,
+  `4` not-found, `5` connection, `6` config, `7` conflict, `8` unavailable).
+- **Writes:** dry-run by default; `--apply` is the only gate and a dry-run opens
+  no connection.

vcf_super_cli-0.4.0/docs/index.md

@@ -0,0 +1,46 @@
+# vcf-super-cli
+
+A modern, agent-friendly CLI for **VMware Cloud Foundation 9** whose command tree
+is **generated dynamically** from the official [`vcf-sdk`](https://pypi.org/project/vcf-sdk/)
+vAPI bindings.
+
+```console
+$ vsc vsphere vm list --power-states POWERED_ON --profile prod
+$ vsc nsx segments list --all --output table
+$ vsc vsphere perf vm vm-42 --metric cpu.usage
+```
+
+!!! warning "Pre-1.0"
+    Reads and writes are both available. **Writes are dry-run by default** —
+    nothing changes without `--apply`. See [Writes](writes.md). While on `0.x`,
+    minor versions may include breaking changes.
+
+## Highlights
+
+- **Mirrors the real API** — commands come from the SDK's vAPI metadata, covering
+  vCenter and NSX from one generator.
+- **Ergonomic** — offline tab-completion (enums, formats, profiles, filter
+  choices), per-field `--<field>` filter flags, and paging (`--all` /
+  `--max-items` / `--limit`).
+- **pyVmomi fallback** — read-only `perf`, `events`, `tasks`, and `inventory`
+  commands for areas the REST/vAPI surface doesn't cover.
+- **Safe by default** — writes are dry-run unless `--apply`; a dry-run never connects.
+- **Agent-friendly** — JSON output, stable error envelope, documented exit codes,
+  bundled agent Skill.
+
+See the [Design](design.md) for how dynamic generation works, and
+[Commands](commands.md) for the full surface.
+
+## Install
+
+```sh
+uv tool install vcf-super-cli       # or: pip install vcf-super-cli
+vsc --install-completion            # optional: offline shell completion
+```
+
+From source:
+
+```sh
+uv sync
+uv run vsc --help
+```

{vcf_super_cli-0.3.0 → vcf_super_cli-0.4.0}/docs/usage.md

@@ -30,8 +30,35 @@ Completion is **fully offline** — it never opens a connection. It suggests:
 - configured profile names (`--profile <TAB>`),
 - and per-field `list` filter enum choices.
 
-Completing a live resource id (e.g. `<vm>` from a real inventory) would require a
-network call and is deliberately **not** done in this release.
+### Live resource-id completion (opt-in)
+
+Completing a real id (e.g. `<vm>` from the live inventory) does require a network
+call, so it is **opt-in** and off by default:
+
+```sh
+export VSC_COMPLETE_DYNAMIC=1
+vsc vsphere vm get <TAB>          # → vm-101  vm-102 …  (real ids, names as help)
+```
+
+When enabled, pressing `<TAB>` on an id-typed argument or option suggests live
+ids for that resource type (VMs, hosts, clusters, datacenters, datastores,
+resource pools), showing each resource's name as completion help.
+
+It is built to never get in your way:
+
+- **Off by default.** Without `VSC_COMPLETE_DYNAMIC`, `<TAB>` stays fully offline
+  (the suggestions above are all you get).
+- **Cached.** Results are cached per profile/backend/resource-type under the
+  platform cache dir with a short TTL (default 60s; override with
+  `VSC_COMPLETE_TTL=<seconds>`), so repeated presses don't re-hit the API.
+- **Bounded and fail-soft.** The fetch is abandoned after a short timeout
+  (`VSC_COMPLETE_TIMEOUT`, default 2s); any error, missing auth, or timeout
+  yields no suggestions — `<TAB>` never hangs or prints a traceback.
+- **`--help` is always offline.** Only the shell-completion subprocess ever
+  fetches; `--help` and command execution are unaffected.
+
+This is a convenience only. The agent contract is unchanged: don't rely on
+completion for correctness — list commands remain the source of truth for ids.
 
 ## Error envelope
 

{vcf_super_cli-0.3.0 → vcf_super_cli-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vcf-super-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "Modern, agent-friendly CLI for VMware Cloud Foundation 9, with a command tree generated dynamically from the vcf-sdk vAPI bindings."
 readme = "README.md"
 requires-python = ">=3.12"

vcf_super_cli-0.4.0/tests/test_complete_cache.py

@@ -0,0 +1,107 @@
+"""On-disk TTL cache for live completion candidates.
+
+The cache keeps ``<TAB>`` fast and stops repeated completions from re-hitting the
+API. It is fail-soft by contract: a missing, corrupt or unwritable cache is a
+miss, never an exception — completion must never error or hang.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from vsc.gen.complete_cache import cache_dir, cache_ttl, get_or_fetch
+
+
+@pytest.fixture(autouse=True)
+def _tmp_cache(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("VSC_CACHE_DIR", str(tmp_path))
+    monkeypatch.delenv("VSC_COMPLETE_TTL", raising=False)
+
+
+def test_hit_within_ttl_skips_fetch() -> None:
+    calls = 0
+
+    def fetch() -> list[tuple[str, str]]:
+        nonlocal calls
+        calls += 1
+        return [("vm-1", "web"), ("vm-2", "db")]
+
+    first = get_or_fetch("k", ttl=60.0, fetch_fn=fetch, now=1000.0)
+    second = get_or_fetch("k", ttl=60.0, fetch_fn=fetch, now=1059.0)
+    assert first == [("vm-1", "web"), ("vm-2", "db")]
+    assert second == first
+    assert calls == 1  # served from cache the second time
+
+
+def test_expired_entry_refetches() -> None:
+    calls = 0
+
+    def fetch() -> list[tuple[str, str]]:
+        nonlocal calls
+        calls += 1
+        return [(f"vm-{calls}", "x")]
+
+    get_or_fetch("k", ttl=60.0, fetch_fn=fetch, now=1000.0)
+    again = get_or_fetch("k", ttl=60.0, fetch_fn=fetch, now=1061.0)
+    assert calls == 2
+    assert again == [("vm-2", "x")]
+
+
+def test_corrupt_file_is_a_miss() -> None:
+    # Pre-create a garbage cache file at the key's path; get_or_fetch must treat
+    # it as a miss and never raise.
+    get_or_fetch("k", ttl=60.0, fetch_fn=lambda: [("a", "a")], now=0.0)
+    files = list(cache_dir().glob("*.json"))
+    assert files
+    files[0].write_text("}{ not json", encoding="utf-8")
+    out = get_or_fetch("k", ttl=60.0, fetch_fn=lambda: [("b", "b")], now=1.0)
+    assert out == [("b", "b")]
+
+
+def test_cache_dir_created_lazily() -> None:
+    assert not cache_dir().exists()
+    get_or_fetch("k", ttl=60.0, fetch_fn=lambda: [("a", "a")], now=0.0)
+    assert cache_dir().exists()
+
+
+def test_write_failure_is_failsoft(monkeypatch: pytest.MonkeyPatch) -> None:
+    def boom(*_a: object, **_k: object) -> None:
+        raise OSError("disk full")
+
+    monkeypatch.setattr("vsc.gen.complete_cache.os.replace", boom)
+    out = get_or_fetch("k", ttl=60.0, fetch_fn=lambda: [("a", "n")], now=0.0)
+    assert out == [("a", "n")]  # fetched value still returned despite write failure
+
+
+def test_items_round_trip_as_tuples() -> None:
+    get_or_fetch("k", ttl=60.0, fetch_fn=lambda: [("vm-1", "web")], now=0.0)
+    out = get_or_fetch("k", ttl=60.0, fetch_fn=lambda: [("zzz", "zzz")], now=1.0)
+    assert out == [("vm-1", "web")]
+    assert all(isinstance(item, tuple) and len(item) == 2 for item in out)
+
+
+def test_malformed_entries_in_payload_are_dropped() -> None:
+    get_or_fetch("k", ttl=60.0, fetch_fn=lambda: [("a", "n")], now=0.0)
+    path = next(iter(cache_dir().glob("*.json")))
+    path.write_text(
+        json.dumps({"ts": 0.0, "items": [["ok", "name"], "bad", ["x"], [1, 2, 3]]}),
+        encoding="utf-8",
+    )
+    out = get_or_fetch("k", ttl=60.0, fetch_fn=lambda: [("z", "z")], now=1.0)
+    assert out == [("ok", "name")]
+
+
+def test_cache_ttl_env_override(monkeypatch: pytest.MonkeyPatch) -> None:
+    assert cache_ttl() == 60.0
+    monkeypatch.setenv("VSC_COMPLETE_TTL", "5")
+    assert cache_ttl() == 5.0
+    monkeypatch.setenv("VSC_COMPLETE_TTL", "not-a-number")
+    assert cache_ttl() == 60.0  # invalid -> default, never raises
+
+
+def test_cache_dir_under_override() -> None:
+    assert cache_dir().parent == Path(__import__("os").environ["VSC_CACHE_DIR"])
+    assert cache_dir().name == "completion"

vcf_super_cli-0.4.0/tests/test_complete_dynamic.py

@@ -0,0 +1,205 @@
+"""Live id completion: opt-in, cached, timeout-bounded, blanket fail-soft.
+
+No real vCenter is touched — the list-op fetch (`_fetch_ids`) is mocked. These
+tests pin the safety contract: off by default, never raise, never hang, and
+never cache a failure.
+"""
+
+from __future__ import annotations
+
+import inspect
+import time
+from pathlib import Path
+from typing import ClassVar
+
+import pytest
+
+from vsc.gen import complete_dynamic as cd
+from vsc.gen.builder import _build_signature
+from vsc.gen.model import Operation, Param, ParamKind
+from vsc.gen.resources import ResourceSource
+
+
+@pytest.fixture(autouse=True)
+def _isolated(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("VSC_CACHE_DIR", str(tmp_path))
+    monkeypatch.delenv("VSC_COMPLETE_DYNAMIC", raising=False)
+    monkeypatch.delenv("VSC_COMPLETE_TTL", raising=False)
+    monkeypatch.delenv("VSC_COMPLETE_TIMEOUT", raising=False)
+    # active profile lookup should be inert in tests
+    monkeypatch.setattr(cd, "active_profile_name", lambda: None)
+
+
+def _fake_items(monkeypatch: pytest.MonkeyPatch, items: list[tuple[str, str]]) -> None:
+    monkeypatch.setattr(cd, "_fetch_ids", lambda _src: list(items))
+
+
+def test_disabled_by_default_returns_empty(monkeypatch: pytest.MonkeyPatch) -> None:
+    # Even a working fetch must not run when the opt-in is unset.
+    def boom(_src: object) -> list[tuple[str, str]]:
+        raise AssertionError("fetch must not run when dynamic completion is disabled")
+
+    monkeypatch.setattr(cd, "_fetch_ids", boom)
+    assert cd.resource_completer("VirtualMachine")("") == []
+
+
+def test_disabled_opens_no_connection(monkeypatch: pytest.MonkeyPatch) -> None:
+    def boom(_backend: str) -> object:
+        raise AssertionError("no connection at <TAB> by default")
+
+    monkeypatch.setattr(cd, "connect_for_backend", boom)
+    assert cd.resource_completer("VirtualMachine")("vm-") == []
+
+
+def test_enabled_returns_ids_prefix_filtered_with_name_help(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("VSC_COMPLETE_DYNAMIC", "1")
+    _fake_items(monkeypatch, [("vm-1", "web"), ("vm-2", "db"), ("host-1", "esx")])
+    complete = cd.resource_completer("VirtualMachine")
+    assert complete("") == [("vm-1", "web"), ("vm-2", "db"), ("host-1", "esx")]
+    assert complete("vm-") == [("vm-1", "web"), ("vm-2", "db")]
+    assert complete("vm-1") == [("vm-1", "web")]
+
+
+def test_cache_hit_avoids_second_fetch(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("VSC_COMPLETE_DYNAMIC", "1")
+    calls = 0
+
+    def fetch(_src: object) -> list[tuple[str, str]]:
+        nonlocal calls
+        calls += 1
+        return [("vm-1", "web")]
+
+    monkeypatch.setattr(cd, "_fetch_ids", fetch)
+    complete = cd.resource_completer("VirtualMachine")
+    complete("")
+    complete("")
+    assert calls == 1  # second press served from cache
+
+
+def test_fetch_error_returns_empty_and_is_not_cached(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("VSC_COMPLETE_DYNAMIC", "1")
+    calls = 0
+
+    def boom(_src: object) -> list[tuple[str, str]]:
+        nonlocal calls
+        calls += 1
+        raise RuntimeError("auth failed")
+
+    monkeypatch.setattr(cd, "_fetch_ids", boom)
+    complete = cd.resource_completer("VirtualMachine")
+    assert complete("") == []
+    assert complete("") == []
+    assert calls == 2  # failure was not cached; it retried
+
+
+def test_timeout_returns_empty(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("VSC_COMPLETE_DYNAMIC", "1")
+    monkeypatch.setenv("VSC_COMPLETE_TIMEOUT", "0.05")
+
+    def slow(_src: object) -> list[tuple[str, str]]:
+        time.sleep(1.0)
+        return [("vm-1", "web")]
+
+    monkeypatch.setattr(cd, "_fetch_ids", slow)
+    assert cd.resource_completer("VirtualMachine")("") == []
+
+
+def test_unknown_resource_type_returns_empty(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("VSC_COMPLETE_DYNAMIC", "1")
+    assert cd.resource_completer("NoSuchType")("") == []
+
+
+def test_none_resource_type_returns_empty(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("VSC_COMPLETE_DYNAMIC", "1")
+    assert cd.resource_completer(None)("") == []
+
+
+def test_extract_handles_plain_and_cursor_results() -> None:
+    src = ResourceSource(
+        backend="vsphere",
+        service_cls=object,
+        list_op=Operation(
+            backend="vsphere",
+            service_cls=object,
+            iface_id="x.VM",
+            op_id="list",
+            method_name="list",
+            cli_verb="list",
+            http_method="GET",
+            url_template="/vm",
+        ),
+        id_field="vm",
+        name_field="name",
+    )
+
+    class Row:
+        def __init__(self, vm: str, name: str) -> None:
+            self.vm = vm
+            self.name = name
+
+    plain = [Row("vm-1", "web"), Row("vm-2", "db")]
+    assert cd._extract(plain, src) == [("vm-1", "web"), ("vm-2", "db")]
+
+    class Cursor:
+        results: ClassVar[list[object]] = [Row("vm-9", "z")]
+
+    assert cd._extract(Cursor(), src) == [("vm-9", "z")]
+
+
+# --------------------------------------------------------------------------- #
+# Builder wiring: ID-kind args/options carry the resource completer
+# --------------------------------------------------------------------------- #
+
+
+def _id_param(*, in_path: bool) -> Param:
+    p = Param(name="vm", kind=ParamKind.ID, required=True, in_path=in_path)
+    p.resource_types = "VirtualMachine"
+    return p
+
+
+def _op_with(param: Param) -> Operation:
+    return Operation(
+        backend="vsphere",
+        service_cls=object,
+        iface_id="com.vmware.vcenter.VM",
+        op_id="get",
+        method_name="get",
+        cli_verb="get",
+        http_method="GET",
+        url_template="/vcenter/vm/{vm}",
+        path_vars=["vm"] if param.in_path else [],
+        params=[param],
+    )
+
+
+def test_id_path_argument_gets_resource_completer() -> None:
+    sig, _spec, _fp = _build_signature(_op_with(_id_param(in_path=True)))
+    arg = sig.parameters["vm"].default
+    assert arg.autocompletion is not None
+    # Inert (offline) by default — no env, so no fetch, returns [].
+    assert arg.autocompletion("") == []
+
+
+def test_id_option_gets_resource_completer() -> None:
+    sig, _spec, _fp = _build_signature(_op_with(_id_param(in_path=False)))
+    opt = sig.parameters["vm"].default
+    assert opt.autocompletion is not None
+    assert opt.autocompletion("") == []
+
+
+def test_id_param_without_resource_type_has_no_completer() -> None:
+    bare = Param(name="vm", kind=ParamKind.ID, required=False, in_path=False)
+    sig, _spec, _fp = _build_signature(_op_with(bare))
+    assert sig.parameters["vm"].default.autocompletion is None
+
+
+def test_building_signature_opens_no_connection(monkeypatch: pytest.MonkeyPatch) -> None:
+    def boom(_backend: str) -> object:
+        raise AssertionError("signature build must stay offline")
+
+    monkeypatch.setattr(cd, "connect_for_backend", boom)
+    sig = inspect.signature  # keep import used
+    assert sig is not None
+    _build_signature(_op_with(_id_param(in_path=True)))  # must not raise

vcf_super_cli-0.4.0/tests/test_resources.py

@@ -0,0 +1,115 @@
+"""The resource-type -> list-op registry that powers live id completion.
+
+The registry is built purely by introspecting the SDK metadata (``discover_all``);
+no network call is involved. It maps a vAPI ``resource_type`` (carried on an
+``ID``-kind :class:`Param`) to the *list* operation that enumerates those ids,
+plus which element fields hold the id and a human-readable name.
+"""
+
+from __future__ import annotations
+
+from vsc.gen.model import Operation, Param, ParamKind
+from vsc.gen.resources import ResourceSource, build_resource_registry, resource_source
+
+
+def test_virtual_machine_resolves_to_vm_list() -> None:
+    src = resource_source("VirtualMachine")
+    assert src is not None
+    assert src.backend == "vsphere"
+    assert src.list_op.cli_verb == "list"
+    assert src.list_op.service_short == "vm"
+    assert src.id_field == "vm"
+    assert src.name_field == "name"
+
+
+def test_host_and_cluster_resolve() -> None:
+    host = resource_source("HostSystem")
+    assert host is not None
+    assert host.backend == "vsphere"
+    assert host.id_field == "host"
+    assert host.name_field == "name"
+
+    cluster = resource_source("ClusterComputeResource")
+    assert cluster is not None
+    assert cluster.id_field == "cluster"
+
+
+def test_unknown_resource_type_returns_none() -> None:
+    assert resource_source("NoSuchType") is None
+
+
+def test_subresource_types_are_unsupported() -> None:
+    # Disk/Ethernet ids only make sense relative to a parent VM (their list op
+    # needs a required ``vm`` path arg), so they are deliberately not registered:
+    # tab-completing them standalone is meaningless.
+    assert resource_source("com.vmware.vcenter.vm.hardware.Disk") is None
+
+
+def test_registry_is_offline_and_covers_core_inventory() -> None:
+    registry = build_resource_registry()
+    # Every core vSphere inventory type the SDK annotates with a resource_type.
+    for rt in (
+        "VirtualMachine",
+        "HostSystem",
+        "ClusterComputeResource",
+        "Datacenter",
+        "Datastore",
+        "ResourcePool",
+    ):
+        assert rt in registry, rt
+        assert isinstance(registry[rt], ResourceSource)
+
+
+def test_injected_operations_resolve_without_discovery() -> None:
+    # A by-id "get" op carries the resource_type; the sibling "list" op (same
+    # service, no required path arg) yields the ids. The builder must correlate
+    # them from an injected op list, never touching discover_all.
+    id_param = Param(name="thing", kind=ParamKind.ID, required=True, in_path=True)
+    id_param.resource_types = "Widget"
+    get_op = Operation(
+        backend="vsphere",
+        service_cls=object,
+        iface_id="com.example.Thing",
+        op_id="get",
+        method_name="get",
+        cli_verb="get",
+        http_method="GET",
+        url_template="/things/{thing}",
+        path_vars=["thing"],
+        params=[id_param],
+    )
+    list_op = Operation(
+        backend="vsphere",
+        service_cls=object,
+        iface_id="com.example.Thing",
+        op_id="list",
+        method_name="list",
+        cli_verb="list",
+        http_method="GET",
+        url_template="/things",
+        params=[],
+    )
+    registry = build_resource_registry([get_op, list_op])
+    src = registry.get("Widget")
+    assert src is not None
+    assert src.list_op is list_op
+
+
+def test_list_op_with_required_path_arg_is_skipped() -> None:
+    # A "list" that needs a parent id is a sub-resource list, not a registry source.
+    id_param = Param(name="child", kind=ParamKind.ID, required=True, in_path=True)
+    id_param.resource_types = "Child"
+    parent = Param(name="parent", kind=ParamKind.ID, required=True, in_path=True)
+    list_op = Operation(
+        backend="vsphere",
+        service_cls=object,
+        iface_id="com.example.Child",
+        op_id="list",
+        method_name="list",
+        cli_verb="list",
+        http_method="GET",
+        url_template="/parents/{parent}/children",
+        path_vars=["parent"],
+        params=[id_param, parent],
+    )
+    assert build_resource_registry([list_op]).get("Child") is None

{vcf_super_cli-0.3.0 → vcf_super_cli-0.4.0}/uv.lock

@@ -1326,7 +1326,7 @@ wheels = [
 
 [[package]]
 name = "vcf-super-cli"
-version = "0.3.0"
+version = "0.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "keyring" },

{vcf_super_cli-0.3.0 → vcf_super_cli-0.4.0}/vsc/_version.py

@@ -4,4 +4,4 @@
 Keep this in sync with `[project].version` in `pyproject.toml`.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"