feat(baremetal): list the servers carrying a tag, filtered by the API

[Denis-hamon]

What this is

The first concrete thing the v2 catalogue buys, now that #262 can fetch its schemas and #263 embeds one.

ovhcloud baremetal list --tag Compliance=PCI-DSS
ovhcloud baremetal list --tag owner:EXISTS
ovhcloud baremetal list --tag owner:NEQ=Denis --tag Team:LIKE=infra%

IAM tags are how a fleet is organised — owner, Compliance, Team, LandingZone — and nothing here could ask for them. The generic --filter cannot: it runs over the columns of the table, after every server has been fetched, and the tags are not among them.

Why it crosses catalogues, and why that is safe

GET /v2/dedicated/server takes an iamTags parameter the v1 collection does not, so the narrowing happens on the API. But the v2 object is {id, iam} — there is no machine in it, so a table built from it would lose every column. The servers it names are therefore read on v1.

The obvious risk is that the two catalogues do not list the same fleet. Measured:

	servers
GET /v1/dedicated/server	35
GET /v2/dedicated/server	35
in one and not the other	0, both ways

Without --tag, nothing changes: the same v1 collection as before, and a test asserts the v2 one is never called.

The syntax is one rule

key[:OPERATOR][=value], with no invented punctuation:

written	means
owner=Denis	EQ, which is the API's own default
owner:EXISTS	set to anything
owner:NEQ=Denis	set to something else
Project:LIKE=Proof%	the API's pattern syntax, passed through untouched

The operator is spelled with the name the API uses, which is what lets a refusal list the ones that exist and completion offer them. It is read from the embedded schema (iam.resource.TagFilter.OperatorEnum) rather than transcribed: a list copied into Go stops being true in silence, which is what the game protocols of #256 cost.

Three refusals, each for a reason:

🛑 unknown tag operator "CONTAINS" in "owner:CONTAINS=Denis"; use one of EQ, EXISTS, ILIKE, LIKE, NEQ, NEXISTS
🛑 EXISTS asks whether "owner" is set at all, so it takes no value ("owner:EXISTS=Denis")
🛑 EQ needs something to compare "owner" against; write owner=<value>, or use EXISTS or NEXISTS to ask whether it is set

The last one matters most: silently turning a valueless comparison into EXISTS would answer a different question and look like it worked. Only the first = separates, so a value may contain another one and the wildcards LIKE uses.

--tag and --filter are not the same thing and both are honoured, in that order — the API narrows, then the table filters.

Measured against the real account

asked	servers	checked against
--tag Compliance=PCI-DSS	4	4 servers carry that tag, read outside the CLI
--tag owner:EXISTS	10	10 carry an owner key
--tag Project:LIKE=Proof%	1	the one server tagged Proof-of-Concept
no --tag	35	the whole fleet
--tag Compliance:NEQ=PCI-DSS	0	right: all four servers with that key carry the same value

Encoding checked the same way: a query whose JSON does not survive answers 400 Parameter iamTags isn't formatted correctly: failed to decode json, and a filter carrying a space answers 200 with an empty list — so the space made it through intact.

Gate

go build, go vet, make wasm, go test ./..., docgen — all clean.

16 tests (11 unit, 5 cobra) and 10 sabotages, 10 red, restoration checked by digest.

One of them was worth the trouble on its own. Removing url.QueryEscape from the query left the test green: url.QueryUnescape returns an unescaped string unchanged, so a round-trip assertion passes on a query that was never escaped at all. The test now refuses to see a raw {, }, ", [ or ] in the query, and the sabotage goes red. The count above is the corrected run.

Stacked on #263 → #262 → #261.

[Denis-hamon]

Human review — Doubt

L1 · The key[:OPERATOR][=value] syntax
Dimension: Naming

Expected: The syntax sticks. Operators carry the API's own names (EQ, NEQ, LIKE, ILIKE, EXISTS, NEXISTS), read from the schema and never retyped.

Rendering pretty ugly with ASCII FORMAT , some '|' are not aligned

— Denis (Product Manager), through CLI sandbox review page

[Denis-hamon]

Human review — Does not work

L3 · A key containing a colon
Dimension: Error message

Expected: A suffix that is not an operator produces a refusal explaining the ambiguity instead of guessing.

🛑 "ovh:default=true" is ambiguous: "default" is not one of EQ, EXISTS, ILIKE, LIKE, NEQ, NEXISTS, so this can only be read as the tag key "ovh:default" with no operator.
If that is what you meant, write the operator out: --tag ovh:default:EQ=
exit 1

— Denis (Product Manager), through CLI sandbox review page

[Denis-hamon]

Two follow-ups from yesterday's human review.

L1 ("Rendering pretty ugly with ASCII FORMAT, some '|' are not aligned"): not a defect in this code. Replayed baremetal list --tag Compliance=PCI-DSS for real (binary built from this branch, live account) and captured the raw bytes — every data row is byte-identical in width to its neighbours, and the border rows match exactly:

327 ┌────────────────────────────┬──────────────────┬────────────────────────────┬──────────────────────┬───────┐
121 │            name            │      region      │        displayName         │          os          │ state │
327 ├────────────────────────────┼──────────────────┼────────────────────────────┼──────────────────────┼───────┤
121 │ ns537688.ip-139-99-131.net │ ap-southeast-syd │ ns537688.ip-139-99-131.net │ win2019-std_64       │ ok    │
...

The table renders correctly in a real terminal. The reviewer saw it through the review sandbox's web page (a separate, internal tool, not this repo): its embedded "IBM Plex Mono" web font is a 218-glyph Latin-only subset with no Unicode box-drawing coverage (checked its cmap directly — ─│┌┐└┘├┤┬┴┼ are all absent, plain ASCII |/- are present). The browser falls back per-glyph to a system font with different metrics for just the border characters, so │ drifts against the ASCII text beside it while the actual CLI output never does. Fixed in the sandbox itself today (rendering terminal output with a system monospace stack instead of the branded webfont) — unrelated repo, no change needed here.

L3 ("A key containing a colon" — --tag ovh:default=true): already matches the expected behaviour. splitTagFilter (internal/services/baremetal/tags.go) refuses it with the ambiguity spelled out, exactly as described:

🛑 "ovh:default=true" is ambiguous: "default" is not one of EQ, EXISTS, ILIKE,
   LIKE, NEQ, NEXISTS, so this can only be read as the tag key "ovh:default"
   with no operator.
   If that is what you meant, write the operator out: --tag ovh:default:EQ=<value>

and --tag ovh:default:EQ=true is accepted. Marking as working as intended.

[Denis-hamon]

Follow-up on L3 — a false negative.

🛑 "ovh:default=true" is ambiguous: "default" is not one of EQ, EXISTS, ILIKE, LIKE, NEQ, NEXISTS,
   so this can only be read as the tag key "ovh:default" with no operator.
   If that is what you meant, write the operator out: --tag ovh:default:EQ=<value>

That is the check's own expected result: "A suffix that is not an operator produces a refusal explaining the ambiguity instead of guessing." The command names the ambiguity, lists the operators, and gives the disambiguating form. Exit 1 is correct here.

The misreading came from the sandbox, which never said a check can be validated by a refusal — a 🛑 and a non-zero exit read as a failure, which is what a terminal teaches. Eight checks are in that case; they now carry the warning before the click, so the reviewer rules on the wording of the refusal rather than on the fact that there is one.

[Denis-hamon]

Human review — Doubt

L3 · A key containing a colon
Dimension: Error message

Expected: A suffix that is not an operator produces a refusal explaining the ambiguity instead of guessing.

🛑 "ovh:default=true" is ambiguous: "default" is not one of EQ, EXISTS, ILIKE, LIKE, NEQ, NEXISTS, so this can only be read as the tag key "ovh:default" with no operator.
If that is what you meant, write the operator out: --tag ovh:default:EQ=

— Denis (Product Manager), through CLI sandbox review page