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

{vcf_super_cli-0.5.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.5.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.5.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.5.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.5.0 → vcf_super_cli-0.6.0}/CHANGELOG.md

@@ -7,6 +7,30 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vcf-super-cli
-Version: 0.5.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/
@@ -76,6 +76,7 @@ $ vsc vsphere power stop vm-42 --apply        # writes are dry-run without --app
 | Ergonomics — offline shell completion, per-field filter flags + paging, pyVmomi fallback (`perf`/`events`/`tasks`/`inventory`) | ✅ v0.3 |
 | 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.5.0 → vcf_super_cli-0.6.0}/README.md

@@ -44,6 +44,7 @@ $ vsc vsphere power stop vm-42 --apply        # writes are dry-run without --app
 | Ergonomics — offline shell completion, per-field filter flags + paging, pyVmomi fallback (`perf`/`events`/`tasks`/`inventory`) | ✅ v0.3 |
 | 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.5.0 → vcf_super_cli-0.6.0}/docs/commands.md

@@ -78,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.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.5.0 → vcf_super_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vcf-super-cli"
-version = "0.5.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.5.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.5.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

{vcf_super_cli-0.5.0 → vcf_super_cli-0.6.0}/uv.lock

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

{vcf_super_cli-0.5.0 → vcf_super_cli-0.6.0}/vsc/_version.py

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

{vcf_super_cli-0.5.0 → vcf_super_cli-0.6.0}/vsc/gen/builder.py

@@ -295,6 +295,7 @@ def make_command(op: Operation, connect_fn: ConnectFn) -> Callable[..., None]:
                     all_flag=bool(kwargs.get(_ALL_PARAM, False)),
                     max_items=kwargs.get(_MAXITEMS_PARAM),
                     limit=kwargs.get(_LIMIT_PARAM),
+                    supports_cursor=any(p.name == "cursor" for p in op.params),
                 )
                 emit(result, fmt)
             elif op.is_write:
@@ -366,16 +367,22 @@ def _run_list(
     all_flag: bool,
     max_items: int | None,
     limit: int | None,
+    supports_cursor: bool = True,
 ) -> Any:
     """Execute a list operation, applying ``--all`` / ``--max-items`` / ``--limit``.
 
     Without any paging flag the raw result is returned unchanged (preserving the
     cursor for manual paging). ``--all`` follows the cursor across pages; the caps
     slice the returned items client-side.
+
+    ``supports_cursor`` guards cursor-following: a few ops (e.g. NSX traceflow
+    observations) return a cursor-shaped result yet take no ``cursor`` *input*, so
+    re-invoking with a cursor would raise. For those ``--all`` degrades to a safe
+    single-page no-op, mirroring how it already no-ops on plain (vSphere) lists.
     """
     first = invoke(**sdk_kwargs)
     if _is_cursor_list(first):
-        if all_flag:
+        if all_flag and supports_cursor:
             # Seed the loop with the page we already fetched (no double-fetch).
             def fetch_page(cursor: str | None) -> tuple[list[Any], str | None]:
                 res = first if cursor is None else invoke(**{**sdk_kwargs, "cursor": cursor})

{vcf_super_cli-0.5.0 → vcf_super_cli-0.6.0}/vsc/gen/discover.py

@@ -184,7 +184,8 @@ def vsphere_services() -> list[type]:
 
 
 # NSX Policy services. Imported defensively so a single moved symbol cannot break
-# the whole NSX surface. v0.2 adds IP pools, DHCP configs and Tier-1 locale services.
+# the whole NSX surface. v0.2 adds IP pools, DHCP configs and Tier-1 locale services;
+# #58 adds Traceflow (config CRUD + restart) and its observations (the traced path).
 _NSX_SERVICE_SPECS: tuple[tuple[str, tuple[str, ...]], ...] = (
     (
         "vcf.nsx.policy.api.v1.infra_client",
@@ -196,6 +197,7 @@ _NSX_SERVICE_SPECS: tuple[tuple[str, tuple[str, ...]], ...] = (
             "IpPools",
             "DhcpServerConfigs",
             "DhcpRelayConfigs",
+            "Traceflows",
         ),
     ),
     (
@@ -203,6 +205,7 @@ _NSX_SERVICE_SPECS: tuple[tuple[str, tuple[str, ...]], ...] = (
         ("Groups", "SecurityPolicies", "GatewayPolicies"),
     ),
     ("vcf.nsx.policy.api.v1.infra.tier_1s_client", ("LocaleServices",)),
+    ("vcf.nsx.policy.api.v1.infra.traceflows_client", ("Observations",)),
 )
 
 

{vcf_super_cli-0.5.0 → vcf_super_cli-0.6.0}/vsc/skill/assets/SKILL.md

@@ -12,7 +12,10 @@ the `vcf-sdk` vAPI bindings and split into two product groups:
   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)
+  gateway-policies, ip-pools, dhcp-server-configs, dhcp-relay-configs, locale-services,
+  traceflows, observations — Traceflow injects a synthetic packet; `traceflows set <id>
+  --traceflow-config '<json>'` starts one and `observations list <traceflow-id>`
+  reads the path it took)
 
 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