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

{vcf_super_cli-0.4.0 → vcf_super_cli-0.6.0}/.github/workflows/docs.yml

@@ -18,9 +18,9 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       - name: Sync (docs)
@@ -29,7 +29,7 @@ jobs:
         run: uv run mkdocs build --strict
       - name: Upload pages artifact
         if: github.ref == 'refs/heads/main'
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5
         with:
           path: site
 
@@ -43,4 +43,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

{vcf_super_cli-0.4.0 → vcf_super_cli-0.6.0}/.github/workflows/e2e.yml

@@ -10,9 +10,9 @@ jobs:
   e2e:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       - name: Sync (dev)

{vcf_super_cli-0.4.0 → vcf_super_cli-0.6.0}/.github/workflows/lint.yml

@@ -13,9 +13,9 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       - name: Sync (dev)

{vcf_super_cli-0.4.0 → vcf_super_cli-0.6.0}/.github/workflows/test.yml

@@ -17,9 +17,9 @@ jobs:
       matrix:
         python-version: ["3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       - name: Set up Python ${{ matrix.python-version }}

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

@@ -7,6 +7,49 @@ versions may include breaking changes.
 
 ## [Unreleased]
 
+## v0.6.0 — 2026-07-03
+
+NSX Traceflow — inject a synthetic packet and read the exact path it takes through
+the topology, the first tool for "why can't A reach B?".
+
+### Added
+
+- **`vsc nsx traceflows` / `vsc nsx observations`** (#58) — NSX Policy Traceflow.
+  Inject a synthetic packet and read the exact path it takes through the topology —
+  the first tool for "why can't A reach B?". `traceflows` exposes the config surface
+  (`list`/`get`/`set`/`patch`/`delete` + the `policy-lm-restart-traceflow` action);
+  `set <id> --traceflow-config '<json>'` starts a trace (dry-run by default, `--apply`
+  to execute). `observations list <traceflow-id>` returns the traced path.
+  Pure allow-list addition — no generator changes; writes, JSON struct bodies and
+  paging come from the existing machinery. Manager API traceflow stays deferred.
+
+### Fixed
+
+- `list --all` no longer crashes on operations that return a cursor-shaped result
+  but take no `cursor` input parameter (e.g. `nsx observations list`). Cursor
+  following is now guarded by whether the op actually accepts a `cursor`; for those
+  that don't, `--all` degrades to a safe single-page no-op instead of re-invoking
+  with a rejected `cursor` kwarg.
+
+## v0.5.0 — 2026-06-08
+
+Find VMs by attribute. Answers the everyday *"which VM has `10.20.3.41`?"* — a
+reverse lookup the REST `vm list` filter can't do, because guest networking lives
+only on the pyVmomi `guest.*` properties.
+
+### Added
+
+- **`vsc vsphere inventory find`** (#54) — locate VMs by guest/runtime attribute
+  without knowing the moid: `--ip` (exact or CIDR, IPv4/IPv6, across the primary and
+  every NIC address), `--name`, `--hostname`, `--guest-os` (case-insensitive
+  substring or glob), `--mac` (exact), and `--power-state`. Flags **AND** together; a
+  repeated flag **ORs** within its field; at least one match flag is required (it
+  refuses to dump the whole inventory). `--props` (repeatable) widens each hit's
+  output only — never a match criterion. One PropertyCollector round-trip over a
+  container view (always destroyed); a pure, pyVmomi-free matcher does the filtering.
+  Reads only — no `--apply` — and emits the same JSON / error envelope / exit codes
+  as the other pyVmomi fallback commands.
+
 ## v0.4.0 — 2026-06-08
 
 Live resource-id completion. Pressing `<TAB>` on an id-typed argument can now

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vcf-super-cli
-Version: 0.4.0
+Version: 0.6.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/
@@ -74,7 +74,9 @@ $ vsc vsphere power stop vm-42 --apply        # writes are dry-run without --app
 | NSX **Policy API** read (`vsc nsx …`) | ✅ v0.1 |
 | Writes — dry-run by default + `--apply` (`vsc vsphere …` / `vsc nsx …`) | ✅ v0.2 |
 | Ergonomics — offline shell completion, per-field filter flags + paging, pyVmomi fallback (`perf`/`events`/`tasks`/`inventory`) | ✅ v0.3 |
-| Live resource-id completion | planned |
+| Live resource-id completion | ✅ v0.4 |
+| Find VMs by attribute — IP / hostname / MAC / guest OS / power (`vsc vsphere inventory find`) | ✅ v0.5 |
+| NSX **Traceflow** — inject a synthetic packet, read its path (`vsc nsx traceflows` / `vsc nsx observations`) | ✅ v0.6 |
 | NSX Manager / Global-Manager, SDDC Manager, Operations, LCM | deferred |
 
 ## Install

{vcf_super_cli-0.4.0 → vcf_super_cli-0.6.0}/README.md

@@ -42,7 +42,9 @@ $ vsc vsphere power stop vm-42 --apply        # writes are dry-run without --app
 | NSX **Policy API** read (`vsc nsx …`) | ✅ v0.1 |
 | Writes — dry-run by default + `--apply` (`vsc vsphere …` / `vsc nsx …`) | ✅ v0.2 |
 | Ergonomics — offline shell completion, per-field filter flags + paging, pyVmomi fallback (`perf`/`events`/`tasks`/`inventory`) | ✅ v0.3 |
-| Live resource-id completion | planned |
+| Live resource-id completion | ✅ v0.4 |
+| Find VMs by attribute — IP / hostname / MAC / guest OS / power (`vsc vsphere inventory find`) | ✅ v0.5 |
+| NSX **Traceflow** — inject a synthetic packet, read its path (`vsc nsx traceflows` / `vsc nsx observations`) | ✅ v0.6 |
 | NSX Manager / Global-Manager, SDDC Manager, Operations, LCM | deferred |
 
 ## Install

{vcf_super_cli-0.4.0 → vcf_super_cli-0.6.0}/docs/commands.md

@@ -51,6 +51,17 @@ API. Those commands live under `vsc vsphere` alongside the generated ones, are
   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 vsphere inventory find [--ip …] [--name …] [--hostname …] [--mac …] [--guest-os …] [--power-state …] [--props …]`
+  — **find VMs by guest/runtime attribute without knowing the moid.** This is the
+  answer to *"which VM has `10.20.3.41`?"*: guest networking isn't in the REST
+  `vm list` filter, so this sweeps every VM's `guest.*` properties in one round-trip.
+  `--ip` accepts an exact address or a CIDR (`10.20.3.0/24`, IPv4 or IPv6) and matches
+  across the primary and every NIC address; `--name`/`--hostname`/`--guest-os` are
+  case-insensitive substring or glob; `--mac` is exact; `--power-state` is one of
+  `poweredOn`/`poweredOff`/`suspended`. Flags **AND** together, a repeated flag **ORs**
+  within its field, and at least one match flag is required. `--props` (repeatable)
+  widens each hit's output only — it never affects matching. Powered-off VMs and those
+  without VMware Tools report no guest IP and won't match `--ip`.
 
 ## `vsc nsx …` (NSX Policy)
 
@@ -67,6 +78,8 @@ Generated from `vcf.nsx.policy`:
 | `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 |
+| `traceflows` | `vsc nsx traceflows set <id> --traceflow-config '<json>' --apply` (start a trace), `vsc nsx traceflows list` |
+| `observations` | `vsc nsx observations list <traceflow-id>` (the traced packet path) |
 
 ## Curated commands
 

{vcf_super_cli-0.4.0 → vcf_super_cli-0.6.0}/docs/design.md

@@ -68,8 +68,11 @@ SOAP API. Those are **hand-written read-only commands** mounted under
   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`.
+(Event/Task managers), and `inventory` — a PropertyCollector property walk
+(`inventory vm`/`host`) plus `inventory find`, which sweeps every VM's `guest.*`
+properties in one round-trip to locate a VM by IP / name / hostname / MAC / guest
+OS / power state (the fields the REST `vm list` filter can't reach). All are
+reads — no `--apply`.
 
 ## Design specs
 
@@ -78,6 +81,7 @@ 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)
+- [v0.5 — find VMs by attribute](https://github.com/thomaschristory/vcf-super-cli/blob/main/docs/superpowers/specs/2026-06-08-vcf-super-cli-v0.5-find-vms-design.md)
 
 ## Contracts
 

{vcf_super_cli-0.4.0 → vcf_super_cli-0.6.0}/docs/index.md

@@ -19,11 +19,13 @@ $ vsc vsphere perf vm vm-42 --metric cpu.usage
 
 - **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`).
+- **Ergonomic** — tab-completion (enums, formats, profiles, filter choices, and
+  opt-in [live resource ids](usage.md#live-resource-id-completion-opt-in)),
+  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.
+  commands for areas the REST/vAPI surface doesn't cover, including
+  `inventory find` to locate a VM by IP / hostname / MAC / guest OS.
 - **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.

{vcf_super_cli-0.4.0 → vcf_super_cli-0.6.0}/docs/profiles.md

@@ -56,6 +56,10 @@ VSC_PROFILE=prod vsc nsx segments list
 | `VSC_VSPHERE_INSECURE` / `VSC_NSX_INSECURE` | `1`/`true` to skip TLS verification (lab/self-signed) |
 | `VSC_CONFIG_FILE` | Override the config file location |
 | `VSC_LOG_LEVEL` | Log level on stderr (default `WARNING`) |
+| `VSC_COMPLETE_DYNAMIC` | `1`/`true` to enable [live resource-id completion](usage.md#live-resource-id-completion-opt-in) (off by default) |
+| `VSC_COMPLETE_TTL` | Live-completion cache TTL in seconds (default `60`) |
+| `VSC_COMPLETE_TIMEOUT` | Hard timeout for a live-completion fetch in seconds (default `2`) |
+| `VSC_CACHE_DIR` | Override the cache directory (where live-completion results are cached) |
 
 !!! warning "TLS"
     Verification is **on by default**. Only set `VSC_*_INSECURE` (or

vcf_super_cli-0.6.0/docs/superpowers/specs/2026-06-08-vcf-super-cli-v0.5-find-vms-design.md

@@ -0,0 +1,78 @@
+# v0.5 — find VMs by attribute
+
+**Milestone:** v0.5 — find VMs · **Issue:** #54 · **Date:** 2026-06-08
+
+## Problem
+
+You can `vsc vsphere vm list` and filter on what the vAPI `VM.FilterSpec` exposes
+(names, power states, hosts, clusters, datacenters, folders, resource pools).
+None of the **guest/runtime network fields** are filterable there, so the everyday
+question *"which VM has `10.20.3.41`?"* is unanswerable from the CLI. Guest
+networking lives only on the pyVmomi `guest.*` properties; the per-VM REST guest
+API needs the moid first, useless for a reverse lookup.
+
+## Command
+
+```
+vsc vsphere inventory find [--ip ...] [--name ...] [--hostname ...] [--mac ...]
+                           [--guest-os ...] [--power-state ...] [--props ...] [-o ...]
+```
+
+Third command under `inventory_app`, next to `vm`/`host`. VM-focused for v1.
+
+### Match semantics
+
+- Flags **AND** together; a repeated flag **ORs** within that field.
+- `--ip` matches any address across `guest.ipAddress` + every `guest.net[].ipAddress`,
+  as an **exact IP or CIDR** via stdlib `ipaddress` (IPv4 and IPv6). An exact IP is
+  just a `/32` (or `/128`) network, so one code path covers both.
+- `--name`, `--hostname`, `--guest-os` are case-insensitive **substring**, or
+  **glob** when the pattern has `*?[`. `--name` is fully client-side (one matcher).
+- `--mac` exact, case-insensitive, against `guest.net[].macAddress`.
+- `--power-state` ∈ {poweredOn, poweredOff, suspended} against `runtime.powerState`.
+- **No match flag → usage error** (exit 2); we refuse to dump the whole inventory.
+  `--props`/`-o` alone do not count.
+
+### `--props` passthrough (output only)
+
+Repeatable; mirrors `inventory vm --props`. Appends arbitrary property paths to the
+single PropertyCollector retrieve so each **matched** VM also surfaces them under a
+`properties` sub-dict — bridging search→inspect in one call. Never a match criterion.
+
+## Implementation
+
+`vsc/pyvmomi/find.py`:
+
+- **Pure matcher** (`Criteria`, `matches`, `summarize`, `validate_criteria`, plus
+  `_ip_match`/`_text_match`/`_addresses`/`_macs`) — operates only on a plain
+  props dict, no pyVmomi import in the hot path, so it unit-tests in isolation.
+- **One round-trip** (`find_matches` → `_retrieve_all_vms`): a
+  `CreateContainerView(rootFolder, [vim.VirtualMachine], recursive=True)` plus a
+  single `RetrieveContents` with a `TraversalSpec` pulling the fixed search paths
+  **plus** any `--props`. The container view is **always destroyed** in a `finally`.
+
+`vsc/pyvmomi/inventory.py` adds the thin `find` command: builds `Criteria` from the
+flags, rejects an empty criteria set and malformed `--ip`/`--power-state` as usage
+errors, and emits through the shared `run_read` runner (same JSON / error envelope /
+exit codes as the other pyVmomi reads).
+
+### Per-hit shape
+
+```json
+{ "obj": {"type": "VirtualMachine", "value": "vm-101"},
+  "name": "web-1", "power_state": "poweredOn",
+  "ip_addresses": ["10.20.3.41"], "hostname": "web-1.corp",
+  "guest_os": "Ubuntu Linux (64-bit)",
+  "properties": { "config.version": "vmx-19" } }   // only with --props
+```
+
+No matches → empty array, exit 0.
+
+## Scope / non-goals (v1)
+
+- vSphere/pyVmomi only; NSX has its own search surface.
+- VMs only (no host/network/datastore search yet).
+- Single `RetrieveContents` (no paging). Very large inventories may later want
+  `RetrievePropertiesEx` + `maxObjects` paging — a scaling follow-up.
+- VMs without VMware Tools / powered-off report no (or stale) guest IP and won't
+  match `--ip`; expected, noted in the docs.

vcf_super_cli-0.6.0/docs/superpowers/specs/2026-07-02-vcf-super-cli-nsx-traceflow-design.md

@@ -0,0 +1,107 @@
+# NSX Traceflow support
+
+**Milestone:** v0.6 — NSX Traceflow · **Issue:** #58 · **Date:** 2026-07-02
+
+## Problem
+
+NSX Traceflow injects a synthetic packet at a source port and reports the exact
+path it takes through the logical and physical topology — the first tool you reach
+for when debugging "why can't A talk to B?". The `vcf-nsx` SDK ships the Policy
+Traceflow services, but `vsc nsx` doesn't expose them: the NSX surface is a curated
+allow-list (`_NSX_SERVICE_SPECS` in `vsc/gen/discover.py`) and Traceflow isn't on it.
+
+## Approach
+
+Pure allow-list addition. The generator already handles everything Traceflow needs —
+dry-run writes with `--apply`, JSON struct bodies, path-var mapping, cursor paging —
+so no generator changes are required. Add two Policy service classes to the catalog
+and let discovery produce the commands.
+
+## Surface
+
+Two Policy services (Manager API stays deferred, out of scope):
+
+| Service class | Module | Group |
+|---|---|---|
+| `Traceflows` | `vcf.nsx.policy.api.v1.infra_client` | `vsc nsx traceflows` |
+| `Observations` | `vcf.nsx.policy.api.v1.infra.traceflows_client` | `vsc nsx observations` |
+
+### `vsc nsx traceflows`
+
+| Verb | HTTP | Notes |
+|---|---|---|
+| `list` | GET | list traceflow configs; gets `--all`/`--max-items`/`--limit` |
+| `get <traceflow-id>` | GET | read one config |
+| `set <traceflow-id> --traceflow-config '<json>'` | PUT | create/replace a config (start a trace) |
+| `patch <traceflow-id> --traceflow-config '<json>'` | PATCH | partial update |
+| `delete <traceflow-id>` | DELETE | remove a config |
+| `policy-lm-restart-traceflow <traceflow-id>` | POST | restart action |
+
+### `vsc nsx observations`
+
+| Verb | HTTP | Notes |
+|---|---|---|
+| `list <traceflow-id>` | GET | the traced packet path (the actual result) |
+
+## Behavior (inherited from existing infra — no new code)
+
+- **Dry-run by default.** `set`/`patch`/`delete`/restart preview the resolved request
+  and open no connection; `--apply` executes.
+- **`--traceflow-config` is a STRUCT** → accepts a JSON blob, validated client-side
+  before any connection. Malformed/incomplete JSON → clean usage error (exit 2).
+- **Paging.** `traceflows list` is cursor-paginated (`--all` / `--max-items` /
+  `--limit`). `observations list` returns a cursor-shaped result but takes no
+  `cursor` *input*, so `--all` degrades to a safe single-page no-op (see the
+  generator guard added in review below) rather than re-invoking with a cursor.
+- **Read contract holds.** Under `read_only=True` both services yield only `get`/`list`
+  GETs, preserving the invariant asserted by `test_expanded_catalog_read_contract_holds`.
+
+## Accepted quirks (deliberate — no special-casing)
+
+- `observations` is its own top-level group, not nested under `traceflows`. This is
+  how the generic generator names groups (by service short name); nesting would need
+  a per-service override the generator doesn't have.
+- The restart verb is the verbose `policy-lm-restart-traceflow` (POST with no
+  `?action=`, so the op id is kebab-cased). Renaming is a separate cross-cutting
+  concern, not part of this issue.
+
+## Testing
+
+Extend `tests/test_discover.py` (offline, against the real installed SDK):
+
+1. `nsx_services()` includes `Traceflows` and `Observations`.
+2. `traceflows` discovery yields `list`/`get`/`set`/`patch`/`delete` with the right
+   HTTP methods, and `--traceflow-config` is a required STRUCT body on `set`.
+3. `observations` discovery yields a `list` whose required `traceflow_id` is a path
+   param.
+4. The read-only contract still holds across the expanded catalog (existing test
+   covers the new services automatically).
+
+Builder-level (`tests/test_builder.py` style): `traceflows set` without `--apply`
+emits a dry-run request plan and opens no connection.
+
+## Docs
+
+- README scope table: add a Traceflow row (or fold into NSX Policy).
+- `docs/commands.md`: add `traceflows` / `observations` to the NSX table with a
+  create→observe example.
+- `vsc/skill/assets/SKILL.md`: add the two groups to the NSX group list.
+- `CHANGELOG.md`: Added entry under Unreleased.
+
+## Out of scope
+
+- Manager API traceflow (`vcf.nsx.api.v1`).
+- Group-nesting / verb-renaming ergonomics (separate issue if wanted).
+
+## Review follow-ups (adversarial pass)
+
+- **Critical (fixed):** `observations list --all` crashed — the op returns a
+  cursor-shaped result but takes no `cursor` input, so `follow_cursor` re-invoked
+  with `cursor=…` and the SDK method raised `TypeError`. Fixed generically in
+  `_run_list` via a `supports_cursor` guard (only follow when the op has a `cursor`
+  input param); `--all` now no-ops for such ops, matching plain-list behaviour.
+- **Docs (fixed):** `observations list`'s `traceflow_id` is a path variable →
+  positional argument (`list <traceflow-id>`), not a `--traceflow-id` option.
+- **Coverage (added):** restart verb asserted in discovery (POST) and its dry-run
+  gate covered at builder level; explicit `cli_verb == "list"` assertion for
+  observations; regression test for the `--all` no-op.

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

@@ -1,6 +1,6 @@
 [project]
 name = "vcf-super-cli"
-version = "0.4.0"
+version = "0.6.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 → vcf_super_cli-0.6.0}/tests/test_builder.py

@@ -259,6 +259,76 @@ def test_write_apply_routes_named_body_op() -> None:
     assert "segment" in _CAPTURED  # body struct routed to the SDK method
 
 
+def test_traceflows_set_dry_run_emits_put_body_and_never_connects() -> None:
+    # #58: the new NSX Traceflow write surface must inherit the dry-run gate —
+    # preview a PUT with the traceflow-config body, opening no connection.
+    calls: list[str] = []
+
+    def connect(backend: str) -> object:
+        calls.append(backend)
+        return object()
+
+    op = _write("Traceflows", "set", "nsx")
+    app = _write_app(op, object, connect)
+    result = runner.invoke(app, ["tf-1", "--traceflow-config", '{"display_name": "tf-web"}'])
+    assert result.exit_code == 0, result.stdout
+    env = json.loads(result.stdout)
+    assert env["applied"] is False
+    assert env["request"]["method"] == "PUT"
+    assert env["request"]["body"] == {"display_name": "tf-web"}
+    assert calls == []  # invariant: dry-run opens no connection
+
+
+def test_traceflows_restart_dry_run_gate_never_connects() -> None:
+    # #58: the restart action (POST, no ?action=) is a write and must inherit the
+    # dry-run gate — preview and open no connection without --apply.
+    calls: list[str] = []
+
+    def connect(backend: str) -> object:
+        calls.append(backend)
+        return object()
+
+    op = _write("Traceflows", "policy-lm-restart-traceflow", "nsx")
+    app = _write_app(op, object, connect)
+    result = runner.invoke(app, ["tf-1"])  # no --apply
+    assert result.exit_code == 0, result.stdout
+    env = json.loads(result.stdout)
+    assert env["applied"] is False
+    assert env["request"]["method"] == "POST"
+    assert calls == []  # invariant: dry-run opens no connection
+
+
+def test_observations_list_all_on_non_cursor_op_does_not_crash() -> None:
+    # #58: observations list returns a cursor-shaped result but the op takes NO
+    # cursor input param. --all must not re-invoke with a cursor kwarg (which the
+    # SDK method rejects) — it degrades to a safe single-page no-op, like vSphere.
+    invocations: list[dict[str, object]] = []
+
+    class Res:
+        def __init__(self, cursor: str | None) -> None:
+            self.results = [{"hop": 1}]
+            self.cursor = cursor
+
+    class FakeObs:
+        def __init__(self, _cfg: object) -> None:
+            pass
+
+        def policy_lm_list_traceflow_observations(self, **kwargs: object) -> Res:
+            invocations.append(kwargs)
+            if "cursor" in kwargs:
+                raise TypeError("unexpected keyword argument 'cursor'")
+            return Res("PAGE2")  # server hands back a cursor
+
+    obs = next(c for c in nsx_services() if c.__name__ == "Observations")
+    op = next(o for o in discover_operations(obs, "nsx") if o.cli_verb == "list")
+    app = _app_for(op, FakeObs)
+    result = runner.invoke(app, ["tf-1", "--all"])
+    assert result.exit_code == 0, result.stdout or repr(result.exception)
+    # The op takes no cursor input, so --all must invoke exactly once and never
+    # forward a cursor kwarg — no attempt to follow the returned cursor.
+    assert invocations == [{"traceflow_id": "tf-1"}]
+
+
 def _synthetic_write_with_param(param_name: str) -> Operation:
     return Operation(
         backend="vsphere",

{vcf_super_cli-0.4.0 → vcf_super_cli-0.6.0}/tests/test_discover.py

@@ -159,6 +159,49 @@ def test_expanded_catalog_read_contract_holds() -> None:
             assert op.cli_verb in {"get", "list"}
 
 
+# --------------------------------------------------------------------------- #
+# NSX Traceflow (#58)
+# --------------------------------------------------------------------------- #
+
+
+def test_nsx_catalog_includes_traceflow_services() -> None:
+    names = {c.__name__ for c in nsx_services()}
+    assert {"Traceflows", "Observations"} <= names
+
+
+def _traceflow_ops() -> list[Operation]:
+    tf = next(c for c in nsx_services() if c.__name__ == "Traceflows")
+    return discover_operations(tf, "nsx", read_only=False)
+
+
+def test_traceflows_expose_crud_verbs() -> None:
+    by_verb = {o.cli_verb: o for o in _traceflow_ops()}
+    assert by_verb["list"].http_method == "GET"
+    assert by_verb["get"].http_method == "GET"
+    assert by_verb["set"].http_method == "PUT"
+    assert by_verb["patch"].http_method == "PATCH"
+    assert by_verb["delete"].http_method == "DELETE"
+    # The restart action is a POST with no ?action=, so it keeps its kebab op id.
+    assert by_verb["policy-lm-restart-traceflow"].http_method == "POST"
+
+
+def test_traceflows_set_body_is_required_struct() -> None:
+    set_op = next(o for o in _traceflow_ops() if o.cli_verb == "set")
+    cfg = next(p for p in set_op.params if p.name == "traceflow_config")
+    assert cfg.kind is ParamKind.STRUCT
+    assert cfg.required
+    assert cfg.is_body
+
+
+def test_observations_list_has_required_traceflow_id_path_param() -> None:
+    obs = next(c for c in nsx_services() if c.__name__ == "Observations")
+    ops = discover_operations(obs, "nsx")
+    assert [o.cli_verb for o in ops] == ["list"]  # single read op, verb is 'list'
+    tid = next(p for p in ops[0].params if p.name == "traceflow_id")
+    assert tid.in_path  # -> positional CLI argument, not a --traceflow-id option
+    assert tid.required
+
+
 def test_action_from_url_edge_cases() -> None:
     assert _action_from_url("/x?action=revise") == "revise"
     assert _action_from_url("/x?force=true&action=reprocess") == "reprocess"  # not first