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

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

@@ -7,6 +7,42 @@ versions may include breaking changes.
 
 ## [Unreleased]
 
+## v0.3.0 — 2026-06-05
+
+Ergonomics: friendlier filtering and paging, offline shell completion, and a
+pyVmomi fallback surface for gaps the REST/vAPI layer doesn't cover. The
+agent-facing contract is unchanged — stable JSON, error envelope, exit codes,
+and writes still dry-run by default.
+
+### Added
+
+- **Static shell completion** (#32), fully offline — never opens a connection.
+  Completes enum option choices, output formats, configured profile names, and
+  `list` filter enum values. Install with `vsc --install-completion`. (Live
+  resource-id completion is intentionally deferred to a later release.)
+- **Per-field filter flags** (#33). `list` commands flatten the SDK filter spec
+  into typed `--<field>` options (repeatable for list/set fields; enum choices
+  validated and completed), e.g. `vsc vsphere vm list --power-states POWERED_ON
+  --names web-1`. The raw `--filter '<json>'` blob stays as a base layer that
+  per-field flags override.
+- **Pagination helpers** (#33): `--all` follows the NSX cursor across pages;
+  `--max-items N` caps the total; `--limit N` is a client-side cap for
+  non-paginated (vSphere) lists. Without `--all`, a paginated `list` returns one
+  page and surfaces its `cursor` for manual paging.
+- **pyVmomi fallback commands** (read-only) under `vsc vsphere`, for areas the
+  REST/vAPI surface lacks — same JSON / error-envelope / exit-code contract:
+  - `perf vm|host --metric <group.name>` — performance counters via the
+    PerformanceManager (#34).
+  - `events list [--vm|--host] [--since 1h]` and `tasks list` — recent events
+    and recent/running tasks (#35).
+  - `inventory vm|host [--props <path>]…` — a PropertyCollector property walk
+    (#36).
+
+### Changed
+
+- Documentation and the bundled agent `SKILL.md` describe completion, the filter
+  and paging flags, and the pyVmomi fallback surface.
+
 ## v0.2.0 — 2026-06-05
 
 First PyPI release. Adds the **write** surface on top of the v0.1 read-only

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vcf-super-cli
-Version: 0.2.0
+Version: 0.3.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/
@@ -73,7 +73,8 @@ $ vsc vsphere power stop vm-42 --apply        # writes are dry-run without --app
 | vSphere / vCenter read (`vsc vsphere …`) | ✅ v0.1 |
 | NSX **Policy API** read (`vsc nsx …`) | ✅ v0.1 |
 | Writes — dry-run by default + `--apply` (`vsc vsphere …` / `vsc nsx …`) | ✅ v0.2 |
-| Dynamic shell completion, per-field filter flags, pyVmomi fallback | v0.3 (planned) |
+| Ergonomics — offline shell completion, per-field filter flags + paging, pyVmomi fallback (`perf`/`events`/`tasks`/`inventory`) | ✅ v0.3 |
+| Live resource-id completion | planned |
 | NSX Manager / Global-Manager, SDDC Manager, Operations, LCM | deferred |
 
 ## Install

{vcf_super_cli-0.2.0 → vcf_super_cli-0.3.0}/README.md

@@ -41,7 +41,8 @@ $ vsc vsphere power stop vm-42 --apply        # writes are dry-run without --app
 | vSphere / vCenter read (`vsc vsphere …`) | ✅ v0.1 |
 | NSX **Policy API** read (`vsc nsx …`) | ✅ v0.1 |
 | Writes — dry-run by default + `--apply` (`vsc vsphere …` / `vsc nsx …`) | ✅ v0.2 |
-| Dynamic shell completion, per-field filter flags, pyVmomi fallback | v0.3 (planned) |
+| Ergonomics — offline shell completion, per-field filter flags + paging, pyVmomi fallback (`perf`/`events`/`tasks`/`inventory`) | ✅ v0.3 |
+| Live resource-id completion | planned |
 | NSX Manager / Global-Manager, SDDC Manager, Operations, LCM | deferred |
 
 ## Install

vcf_super_cli-0.3.0/docs/commands.md

@@ -0,0 +1,112 @@
+# Commands
+
+The `vsphere` and `nsx` command trees are **generated from the `vcf-sdk` vAPI
+bindings**, so `vsc --help` (and each sub-`--help`) is always the authoritative,
+version-accurate reference. This page is an overview.
+
+Generated leaves expose both **read** and **write** verbs:
+
+- `list` — list resources (optional `--filter '<json>'`)
+- `get <id>` — fetch one resource by id, **where the SDK provides a by-id GET**
+  (e.g. `vm`, `cluster`, `datacenter`, `datastore`; some leaves such as `host`,
+  `folder`, and `network` are `list`-only)
+- writes — `create`, `delete`, `set` (PUT upsert), `patch`, and action verbs
+  (e.g. `start`/`stop`/`reset` under `power`). **Writes are dry-run by default and
+  require `--apply`** — see [Writes](writes.md).
+
+## `vsc vsphere …` (vCenter)
+
+Generated from `com.vmware.vcenter`:
+
+| Group | Examples |
+|-------|----------|
+| `vm` | `vsc vsphere vm list`, `vsc vsphere vm get <vm>`, `vsc vsphere vm delete <vm> --apply` |
+| `host` | `vsc vsphere host list`, `vsc vsphere host disconnect <host> --apply` |
+| `cluster` | `vsc vsphere cluster list` |
+| `datacenter` | `vsc vsphere datacenter list` |
+| `datastore` | `vsc vsphere datastore list` |
+| `folder` | `vsc vsphere folder list` |
+| `network` | `vsc vsphere network list` |
+| `resource-pool` | `vsc vsphere resource-pool create --spec '<json>' --apply` |
+| `power` | `vsc vsphere power start\|stop\|reset\|suspend <vm> --apply` |
+| `cpu` / `memory` / `disk` / `ethernet` | VM hardware reads + writes, e.g. `vsc vsphere cpu update <vm> --spec '<json>' --apply` |
+| `perf` / `events` / `tasks` / `inventory` | **pyVmomi fallback** (read-only) — perf counters, recent events, recent/running tasks, and a property walk the REST/vAPI surface lacks (see below) |
+
+### pyVmomi fallback commands
+
+A few inventory/performance areas are only reachable over the older pyVmomi SOAP
+API. Those commands live under `vsc vsphere` alongside the generated ones, are
+**read-only** (no `--apply`), and emit the same JSON / error envelope / exit codes.
+
+- `vsc vsphere perf vm <vm> [--metric group.name]… [--max-samples N]` — performance
+  counters via the PerformanceManager. Metrics are `group.name` (e.g. `cpu.usage`)
+  or `group.name.rollup` (e.g. `cpu.usage.average`); repeat `--metric` for several.
+- `vsc vsphere perf host <host> …` — the same for an ESXi host.
+- `vsc vsphere events list [--vm <vm> | --host <host>] [--since 1h] [--max-count N]`
+  — recent events via the EventManager. `--since` takes a duration (`30s`/`15m`/
+  `2h`/`1d`); scope to at most one entity.
+- `vsc vsphere tasks list [--max-count N]` — recent and running tasks via the
+  TaskManager.
+- `vsc vsphere inventory vm <vm> [--props path]…` / `inventory host <host> …` —
+  managed-object properties the REST list ops omit (device tree, custom attributes),
+  via the PropertyCollector. `--props` is repeatable (e.g. `--props config.hardware`);
+  with none, a small per-type summary set is returned.
+
+## `vsc nsx …` (NSX Policy)
+
+Generated from `vcf.nsx.policy`:
+
+| Group | Examples |
+|-------|----------|
+| `segments` | `vsc nsx segments list`, `vsc nsx segments set <id> --segment '<json>' --apply` |
+| `tier0s` / `tier1s` | `vsc nsx tier1s list`, `vsc nsx tier1s set <id> --tier1 '<json>' --apply` |
+| `services` | `vsc nsx services list` |
+| `groups` | `vsc nsx groups list`, `vsc nsx groups delete <domain> <group> --apply` |
+| `security-policies` | `vsc nsx security-policies list` |
+| `gateway-policies` | `vsc nsx gateway-policies list` |
+| `ip-pools` | `vsc nsx ip-pools set <id> --ip-address-pool '<json>' --apply` |
+| `dhcp-server-configs` / `dhcp-relay-configs` | DHCP config reads + writes |
+| `locale-services` | Tier-1 locale services reads + writes |
+
+## Curated commands
+
+- `vsc profiles …` — manage connection profiles (see [Profiles](profiles.md))
+- `vsc skill export <dir> [--apply]` — export the bundled agent Skill
+- `vsc --version`
+
+## Filtering
+
+`list` commands expose each field of the SDK filter spec as its own typed flag.
+List-valued fields are repeatable; enum fields validate their choices and
+tab-complete:
+
+```sh
+vsc --profile prod vsphere vm list --power-states POWERED_ON --names web-1 --names web-2
+```
+
+The raw JSON spec is still accepted as a base layer / escape hatch; per-field
+flags merge **over** it (a flag wins over the same key in the blob):
+
+```sh
+vsc --profile prod vsphere vm list --filter '{"clusters": ["domain-c1"]}' --power-states POWERED_ON
+```
+
+## Pagination
+
+`list` commands accept paging flags:
+
+| Flag | Effect |
+|------|--------|
+| `--all` | follow the cursor and return **every** page (paginated backends, e.g. NSX) |
+| `--max-items N` | cap the total number of items returned |
+| `--limit N` | client-side cap for non-paginated (vSphere) lists |
+
+```sh
+vsc --profile prod nsx segments list --all            # every page, concatenated
+vsc --profile prod nsx segments list --page-size 50   # one page (cursor surfaced for manual paging)
+vsc --profile prod vsphere vm list --limit 20         # first 20 only
+```
+
+Without `--all`, a paginated `list` returns one page and surfaces the `cursor` so
+an agent can drive pagination itself. On non-paginated backends (vSphere) `--all`
+is a no-op — the output stays a plain array.

vcf_super_cli-0.3.0/docs/superpowers/specs/2026-06-05-vcf-super-cli-v0.3-ergonomics-design.md

@@ -0,0 +1,232 @@
+# vcf-super-cli v0.3 — Ergonomics (design)
+
+**Status:** approved 2026-06-05. Milestone: `v0.3 — ergonomics` (#3).
+**Predecessors:** [v0.1 design](2026-06-05-vcf-super-cli-design.md), [v0.2 writes design](2026-06-05-vcf-super-cli-v0.2-writes-design.md).
+
+## Goal
+
+Make the dynamically-generated CLI pleasant to drive by hand and still trivially
+scriptable by an agent. Three independent feature areas, each shipped as its own
+issue/PR under milestone #3:
+
+1. **Static shell completion** — offline tab-completion of enums, output formats,
+   profile names, and per-field filter choices.
+2. **Filter & pagination helpers** — per-field filter flags (augmenting today's
+   `--filter '<json>'` blob) and friendlier paging (`--all`, `--max-items`,
+   `--limit`).
+3. **pyVmomi fallback commands** — hand-written read commands (perf, events/tasks,
+   inventory walk) for gaps the vAPI/REST surface doesn't cover.
+
+The agent contract is unchanged and non-negotiable: stable JSON output, the
+documented error envelope, the frozen exit codes, and **writes stay dry-run by
+default**. The pyVmomi additions are all reads, so they need no `--apply` gate.
+
+## Locked decisions (from brainstorm, 2026-06-05)
+
+- **Completion is static/offline only.** No feature in v0.3 hits the API during
+  `<TAB>`. Live resource-ID completion (e.g. completing `<vm>` from a live list)
+  is explicitly **deferred to v0.4**; the param model already carries
+  `resource_types` so it remains a clean future extension.
+- **Filter flags augment, never replace, `--filter`.** Raw `--filter '<json>'`
+  stays as the base layer / escape hatch; generated per-field flags merge over it.
+- **Pagination:** `--all` auto-follows the NSX cursor; `--max-items` caps total;
+  `--limit` is a client-side cap for non-cursor (vSphere) lists. NSX
+  `--page-size`/`--cursor` already exist as generated query options.
+- **pyVmomi covers all three families** (perf, events/tasks, inventory walk),
+  built on a small shared `SmartConnect` foundation.
+
+---
+
+## Feature 1 — Static shell completion
+
+### Behaviour
+
+Completion values are derived entirely from the introspected `Param` model plus
+local config — never from a network call. `--help` and completion both stay fully
+offline.
+
+Completed surfaces:
+
+| Surface | Source | Example |
+|---------|--------|---------|
+| enum option | `param.enum_values` | `--power-state POWERED_<TAB>` → `POWERED_ON`, `POWERED_OFF` |
+| `--output` / `-o` | `OutputFormat` members | `-o <TAB>` → `json`, `table` |
+| global `--profile` / `-p` | profile names from `load_config()` (offline file read) | `-p <TAB>` → `prod`, `lab` |
+| per-field filter enum flags | reuse enum completer (feature 2) | `--filter-power-state <TAB>` |
+
+Resource-ID args (the `<vm>` positionals) are **not** completed in v0.3.
+
+### Implementation
+
+- New module **`vsc/gen/complete.py`** — pure completer factories:
+  - `enum_completer(values: list[str]) -> Callable[[str], list[str]]`
+  - `profile_completer() -> Callable[[str], list[str]]`
+  Each takes the Click `incomplete` string and returns the prefix-filtered
+  candidate list. No `ctx`/`param` dependency → unit-testable without a shell.
+- **`vsc/gen/builder.py`** `_build_signature`: when a non-path option is built for
+  an `ENUM` param, pass `autocompletion=enum_completer(param.enum_values)` to
+  `typer.Option`. When building `--output`, attach an `OutputFormat` completer.
+- **`vsc/cli/app.py`** main callback: attach `profile_completer()` to `--profile`.
+- Root app already sets `add_completion=True`; document `vsc --install-completion`
+  and `vsc --show-completion` in `docs/usage.md`.
+
+### Tests
+
+`tests/test_complete.py` — completer factories return correctly prefix-filtered
+lists, empty `incomplete` returns all, no match returns `[]`. A smoke test asserts
+generated enum options carry an `autocompletion` callback.
+
+---
+
+## Feature 2 — Filter & pagination helpers
+
+### Per-field filter flags
+
+vCenter list operations take a single `filter` parameter that is a `STRUCT`
+(`VM.FilterSpec` etc.). Today the user must pass it as `--filter '<json>'`. v0.3
+additionally flattens that struct's fields into typed options.
+
+- **Detection:** on a read/list op, a parameter that is `ParamKind.STRUCT` **and
+  named `filter`** is flattened. Write-body structs are *not* flattened — they
+  stay JSON (`--spec`, `--segment`, …).
+- **Generated flags:** each struct field → `--<field>` (kebab-cased). `list`/`set`
+  fields are **repeatable** (`list[str]` annotation, multiple uses accumulate).
+  `enum` fields carry choices in help + the enum completer.
+- **Precedence / merge:** raw `--filter '<json>'` provides the base dict; per-field
+  flags merge **over** it (a flag wins over the same key in the blob). The merged
+  dict is coerced into the FilterSpec via the existing
+  `coerce_struct`/`coerce_value` path — no new coercion logic.
+- **Collisions:** a flattened field whose flag would collide with a reserved option
+  (`--output`, `--apply`) or another option is suffixed using the existing
+  `_sig_name` mechanism.
+
+New helper **`vsc/gen/filters.py`**:
+- `flatten_filter(param: Param) -> list[Param]` — child params for each struct field
+  (built with `param_from_type` on `struct_type.get_field(name)`).
+- `assemble_filter(base_json, field_values, param) -> Any` — merge base + per-field
+  values and coerce into the struct. Pure; unit-testable.
+
+`builder.py` consumes these: `_build_signature` emits the child options (tracking
+them so `_collect_kwargs` knows to reassemble rather than pass them through), and
+`_collect_kwargs` calls `assemble_filter` to rebuild the single `filter` kwarg.
+
+### Pagination
+
+NSX Policy list ops return a `*ListResult` struct (`.results`, `.cursor`,
+`.result_count`) and already expose `cursor`/`page_size` as generated query
+options. vSphere REST list ops return a plain list and do not paginate.
+
+Injected options on **list verbs** (`op.cli_verb == "list"`):
+
+| Flag | Applies to | Effect |
+|------|-----------|--------|
+| `--all` | cursor lists (NSX) | follow `.cursor` across pages, concatenate `.results`, stop at `--max-items` |
+| `--max-items N` | all lists | hard cap on returned items (post-fetch for vSphere, loop-stop for `--all`) |
+| `--limit N` | non-cursor lists (vSphere) | client-side slice of the returned list |
+
+Without `--all`, a cursor list returns one page **including** its `cursor`, so an
+agent can paginate manually. `--all` and `--max-items` interact: the follow loop
+stops once `--max-items` items are collected.
+
+New helper **`vsc/gen/paginate.py`**:
+- `follow_cursor(fetch_page, *, max_items) -> list` — `fetch_page(cursor) ->
+  (results, next_cursor)`; loops until `next_cursor` is empty/repeated or the cap
+  is hit. Pure given the `fetch_page` callable (the callable closes over the SDK
+  method in `builder.py`); unit-testable with a fake pager.
+
+`builder.py` `make_command` detects a cursor-bearing result and, when `--all` is
+set, drives `follow_cursor`; otherwise applies `--limit`/`--max-items` slicing
+before `emit()`.
+
+### Tests
+
+`tests/test_filters.py` — flatten produces one child per field with correct
+kind/required/repeatable; assemble merges blob + flags with flags winning; enum
+field carries choices. `tests/test_paginate.py` — `follow_cursor` concatenates,
+respects `max_items`, terminates on empty/duplicate cursor. Builder integration
+tests assert a vCenter list op grows `--<field>` options and an NSX list op grows
+`--all`/`--max-items`.
+
+---
+
+## Feature 3 — pyVmomi fallback commands
+
+Hand-written read commands for gaps the vAPI/REST surface doesn't cover, mounted
+into the existing `vsc vsphere` tree and emitted through the existing
+`emit()`/error-envelope contract.
+
+### Foundation
+
+- New module **`vsc/connect/vmomi.py`**:
+  - `connect_vmomi() -> ServiceInstance` via `pyVim.connect.SmartConnect`, reusing
+    `resolve_target("vsphere")` for server/user/password and an `ssl` context that
+    honours `verify` (unverified context when `insecure`). Cached like the vAPI
+    connections (`reset_cache()` clears it); `Disconnect` registered at process
+    exit.
+  - `vmomi_jsonable(obj) -> Any` — convert managed-object / data-object trees into
+    plain JSON-able dicts (`moref` → `{"type", "value"}`, data objects → field
+    dicts, leave scalars/datetimes alone) so `emit()` renders them like any other
+    result.
+- New package **`vsc/pyvmomi/`**, one module per family, each exposing a
+  `typer.Typer`. `vsc/cli/app.py` adds them onto the vsphere group
+  (`vsphere_group.add_typer(perf_app, name="perf")`, …). pyVmomi errors
+  (`vim.fault.*`, connection failures) map into the existing envelope/exit codes
+  (auth→3, not-found→4, connection→5) via a small adapter reusing
+  `vsc/output/errors.py` patterns.
+
+### Commands
+
+- **`vsc vsphere perf`** — real-time/historical counters via `PerformanceManager`.
+  e.g. `perf vm <vm> --metric cpu.usage [--interval 20s]`,
+  `perf host <host> --metric mem.usage`. Resolves the counter id, queries
+  `QueryPerf`, emits timestamped samples.
+- **`vsc vsphere events`** — recent events via `EventManager` with `--since`/entity
+  filters. **`vsc vsphere tasks`** — running + recent tasks via `TaskManager`.
+- **`vsc vsphere inventory`** — `PropertyCollector` walk for properties the REST
+  list ops omit (device tree, custom attributes, relationships), e.g.
+  `inventory vm <vm> --props config.hardware`.
+
+All are reads → no `--apply`. They accept the same `--output json|table` and obey
+`--profile`.
+
+### Tests
+
+pyVmomi has no offline-introspection trick like the vAPI bindings, so tests mock
+`SmartConnect`/`ServiceInstance` and the relevant managers. `tests/test_vmomi.py`
+covers `vmomi_jsonable` conversion (moref/data-object/scalar) purely;
+`tests/test_pyvmomi_*.py` drive each command against a fake `ServiceInstance`
+asserting the emitted JSON shape and error mapping. No live vCenter required.
+
+---
+
+## Cross-cutting
+
+- Each feature PR updates the relevant `docs/` page(s) and the bundled
+  `vsc/skill/assets/SKILL.md` for any new surface.
+- `ruff`, `mypy --strict`, `pytest`, and `mkdocs --strict` stay green; CI green
+  before merge.
+- Every PR gets an adversarial **refute-before-accept** review pass; findings are
+  fixed before merge.
+
+## Issues (milestone #3)
+
+| Issue | Title | Depends on |
+|-------|-------|-----------|
+| Epic | v0.3 — ergonomics | — |
+| A | Static shell completion (enums, `--output`, `--profile`, filter choices) | — |
+| B | Filter & pagination helpers (per-field flags + `--all`/`--max-items`/`--limit`) | — |
+| C | pyVmomi fallback foundation + `vsc vsphere perf` | — |
+| D | pyVmomi events & tasks | C |
+| E | pyVmomi inventory walk | C |
+| F | v0.3 docs/SKILL roundup + release prep | A–E |
+
+Build order: A and B in parallel; C → (D, E); F last. The release tag (`vX.Y.Z`)
+is pushed **manually by the maintainer** after F merges — `release.yml` keeps **no
+`environment:` block** (the PyPI trusted publisher is registered with a blank
+environment; they must stay matched).
+
+## Out of scope (v0.3)
+
+- Live resource-ID completion (hits the API) — v0.4 candidate.
+- pyVmomi *writes* — the fallback surface is read-only this milestone.
+- NSX Manager / Global-Manager APIs (still Policy-only).

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

@@ -14,6 +14,25 @@ vsc --profile prod vsphere vm list -o table   # table
 
 Only `json` and `table` are accepted; anything else is rejected with exit code `2`.
 
+## Shell completion
+
+Install completion for your shell once:
+
+```sh
+vsc --install-completion          # bash, zsh, fish, PowerShell
+vsc --show-completion             # print the script instead of installing
+```
+
+Completion is **fully offline** — it never opens a connection. It suggests:
+
+- enum option choices (e.g. `--power-states <TAB>` → `POWERED_ON`, `POWERED_OFF`),
+- output formats (`-o <TAB>` → `json`, `table`),
+- 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.
+
 ## Error envelope
 
 Errors are written to **stderr** as a stable JSON object:

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

@@ -1,6 +1,6 @@
 [project]
 name = "vcf-super-cli"
-version = "0.2.0"
+version = "0.3.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"
@@ -89,10 +89,16 @@ ignore = [
 "vsc/cli/**" = [
     "B008",              # typer.Option/Argument in defaults is the Typer idiom
 ]
+"vsc/pyvmomi/**" = [
+    "B008",              # typer.Option/Argument in defaults is the Typer idiom
+]
 "vsc/gen/**" = [
     "PLR0911",           # type dispatch tables legitimately have many returns
     "PLR0912",           # ...and many branches
 ]
+"vsc/connect/vmomi.py" = [
+    "PLR0911",           # vmomi_jsonable is a type-dispatch table (many returns)
+]
 "tests/**" = [
     "PLR2004",           # magic values in tests are fine
     "PLR0915",           # lifecycle tests legitimately need many statements
@@ -112,6 +118,14 @@ plugins = ["pydantic.mypy"]
 module = ["com", "com.*", "vcf", "vcf.*", "vmware", "vmware.*", "pyVmomi.*", "pyVim.*"]
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+# pyVmomi/pyVim are dynamically typed (attributes synthesized at runtime); skipping
+# their analysis treats their surface as Any rather than flagging every vim.* access
+# and untyped SmartConnect/Disconnect call.
+module = ["pyVmomi", "pyVmomi.*", "pyVim", "pyVim.*"]
+follow_imports = "skip"
+follow_imports_for_stubs = true
+
 [tool.pytest.ini_options]
 addopts = "-ra --strict-markers --strict-config --ignore=tests/e2e"
 testpaths = ["tests"]

{vcf_super_cli-0.2.0 → vcf_super_cli-0.3.0}/tests/test_builder.py

@@ -278,7 +278,7 @@ def _synthetic_write_with_param(param_name: str) -> Operation:
 def test_injected_flags_do_not_collide_with_reserved_param_names() -> None:
     # A write op with a body param literally named 'apply' must not produce two
     # --apply option declarations; the user param is renamed.
-    sig, _spec = _build_signature(_synthetic_write_with_param("apply"))
+    sig, _spec, _fp = _build_signature(_synthetic_write_with_param("apply"))
     decls: list[str] = []
     for p in sig.parameters.values():
         info = p.default

vcf_super_cli-0.3.0/tests/test_complete.py

@@ -0,0 +1,100 @@
+"""Static (offline) shell-completion helpers and their wiring into commands."""
+
+from __future__ import annotations
+
+import inspect
+from typing import ClassVar
+
+import pytest
+
+from vsc.gen.builder import _OUTPUT_PARAM, _build_signature
+from vsc.gen.complete import enum_completer, output_format_completer, profile_completer
+from vsc.gen.model import Operation, Param, ParamKind
+
+
+def test_enum_completer_prefix_filters() -> None:
+    complete = enum_completer(["POWERED_ON", "POWERED_OFF", "SUSPENDED"])
+    assert complete("POWERED_") == ["POWERED_ON", "POWERED_OFF"]
+
+
+def test_enum_completer_empty_incomplete_returns_all() -> None:
+    values = ["A", "B", "C"]
+    assert enum_completer(values)("") == values
+
+
+def test_enum_completer_no_match_returns_empty() -> None:
+    assert enum_completer(["A", "B"])("Z") == []
+
+
+def test_enum_completer_none_incomplete_returns_all() -> None:
+    # Typer's wrapper types incomplete as ``str | None``; a None must not crash
+    # completion — treat it like an empty prefix.
+    assert enum_completer(["A", "B"])(None) == ["A", "B"]  # type: ignore[arg-type]
+
+
+def test_output_format_completer_offers_formats() -> None:
+    assert output_format_completer()("") == ["json", "table"]
+    assert output_format_completer()("t") == ["table"]
+
+
+def test_profile_completer_filters_names(monkeypatch: pytest.MonkeyPatch) -> None:
+    class _Cfg:
+        profiles: ClassVar[dict[str, object]] = {"prod": 1, "prod-eu": 2, "lab": 3}
+
+    monkeypatch.setattr("vsc.gen.complete.load_config", _Cfg)
+    assert profile_completer()("prod") == ["prod", "prod-eu"]
+
+
+def test_profile_completer_is_failsoft(monkeypatch: pytest.MonkeyPatch) -> None:
+    def _boom() -> object:
+        raise RuntimeError("no config readable")
+
+    monkeypatch.setattr("vsc.gen.complete.load_config", _boom)
+    assert profile_completer()("anything") == []  # never raises during <TAB>
+
+
+# --------------------------------------------------------------------------- #
+# Wiring: generated options carry the right completer
+# --------------------------------------------------------------------------- #
+
+
+def _op_with(param: Param) -> Operation:
+    return Operation(
+        backend="vsphere",
+        service_cls=object,
+        iface_id="com.vmware.vcenter.thing",
+        op_id="get",
+        method_name="get",
+        cli_verb="get",
+        http_method="GET",
+        url_template="/vcenter/thing",
+        path_vars=[],
+        path_var_map={},
+        params=[param],
+    )
+
+
+def _option_for(sig: inspect.Signature, sig_name: str) -> object:
+    return sig.parameters[sig_name].default
+
+
+def test_enum_option_gets_autocompletion() -> None:
+    enum_param = Param(name="state", kind=ParamKind.ENUM, required=False, enum_values=["ON", "OFF"])
+    sig, _spec, _fp = _build_signature(_op_with(enum_param))
+    opt = _option_for(sig, "state")
+    assert opt.autocompletion is not None
+    assert opt.autocompletion("O") == ["ON", "OFF"]
+
+
+def test_non_enum_option_has_no_autocompletion() -> None:
+    string_param = Param(name="name", kind=ParamKind.STRING, required=False)
+    sig, _spec, _fp = _build_signature(_op_with(string_param))
+    assert _option_for(sig, "name").autocompletion is None
+
+
+def test_output_option_gets_format_completion() -> None:
+    string_param = Param(name="name", kind=ParamKind.STRING, required=False)
+    sig, _spec, _fp = _build_signature(_op_with(string_param))
+    opt = _option_for(sig, _OUTPUT_PARAM)
+    assert opt.autocompletion is not None
+    assert opt.autocompletion("") == ["json", "table"]