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

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

@@ -7,6 +7,54 @@ versions may include breaking changes.
 
 ## [Unreleased]
 
+## 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
+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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vcf-super-cli
-Version: 0.3.0
+Version: 0.5.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,8 @@ $ 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 Manager / Global-Manager, SDDC Manager, Operations, LCM | deferred |
 
 ## Install

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

@@ -42,7 +42,8 @@ $ 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 Manager / Global-Manager, SDDC Manager, Operations, LCM | deferred |
 
 ## Install

{vcf_super_cli-0.3.0 → vcf_super_cli-0.5.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)
 

vcf_super_cli-0.5.0/docs/design.md

@@ -0,0 +1,93 @@
+# 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
+(`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
+
+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
+
+- **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.5.0/docs/index.md

@@ -0,0 +1,48 @@
+# 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** — 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, 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.
+
+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.5.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.5.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.3.0 → vcf_super_cli-0.5.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.5.0}/pyproject.toml

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