feat(openapi): enforce required query params, add --query escape hatch

[dspangen]

Two query-param gaps fixed on generated commands:

• Spec-required query params are now enforced client-side (required flag(s) "q" not set, (required) in help, and an empty value like --q= is also rejected) — previously a missing one cost a full round trip to a server 400.
• New repeatable --query key=value escape hatch sends params the spec doesn't declare — previously such operations were simply uncallable (one audited incident burned 45k tokens before giving up). Keys go out verbatim; conflicts with an explicitly set declared flag error instead of silently picking one.

omni <cmd> --schema still works with zero flags — required-flag enforcement is toggled off for schema runs.

Details: semantics, the --schema design note, and verification

What changed

• Spec-required query params are MarkFlagRequired and labelled (required) in their flag usage. Missing one fails locally with cobra's standard required flag(s) "q" not set. A checkRequiredQueryParams pass in RunE also rejects explicitly empty values (--q=, --q "") against the assembled query string, so the escape-hatch spellings are covered too.
• Every generated command gets a repeatable --query key=value (StringArray) escape hatch. Values merge into the query string alongside declared flags.
  • Keys are sent verbatim — no case or separator normalization, the server sees exactly what was typed.
  • Repeating a key sends every value (--query tag=a --query tag=b → tag=a&tag=b), for array-shaped params.
  • A --query key that duplicates an explicitly set declared flag is ambiguous and errors rather than silently picking one. Both spellings are caught (--query connectionId= and --query connectionid= both conflict with --connectionid). If the declared flag is unset, --query may supply its value.
  • Malformed values get a clear error: invalid --query value "nope": expected key=value.
• Collision guard: --query is registered after spec params and body-shorthand flags, behind a Lookup(...) == nil check, so an operation that declares a param slugifying to query keeps its own flag instead of panicking pflag (same defensive pattern as --field/--depth).
• omni agent-help documents both behaviors.

The --schema interaction (design note)

Cobra validates required flags in execute() after PreRunE but before RunE, so the existing --schema short-circuit (which wraps Args and RunE) could not cover them — omni <cmd> --schema would have started failing on operations with required query params, breaking zero-friction discovery.

Approach chosen: a PreRunE that rewrites the BashCompOneRequiredFlag annotation for this invocation — "false" when --schema is present, "true" otherwise. It's registered only when the operation actually has required query params.

Rejected alternatives:

• Mark required only when --schema is absent from os.Args — untestable in-process (the test binary's argv is not the command's) and couples flag wiring to process argv.
• Clear the annotation in PreRunE — would leave the requirement relaxed for any later invocation on the same command object. Rewriting it every run is self-healing.

Verification

• make build — clean; make test — all packages pass.
• New tests in internal/openapi/generate_test.go: required param missing → client-side error + (required) in usage; required param present → in query string; explicitly empty required values rejected end-to-end (--connectionid=, --connectionid "") and via a table test over the assembled query (both spellings, multi-value, optional-empty-is-fine); --query merges extras incl. repeated and empty values; malformed --query errors; --query conflicting with a set declared flag errors (both spellings); no conflict when the declared flag is unset; a spec param named query keeps the flag; --schema works with no flags while the same operation still enforces the required param without --schema.
• Manual smoke against the built binary (5 spec operations have required query params today: content search, ai-eval runs-list, models dbt-sync, models yaml-delete, query wait):

$ ./bin/omni content search
Error: required flag(s) "q" not set

$ ./bin/omni content search --q=
Error: required flag(s) "q" cannot be empty

$ ./bin/omni content search --q foo --query q=bar
Error: --query q=... conflicts with --q; set that parameter one way or the other

$ ./bin/omni content search --help
      --q string            Free-text keywords ... (required)
      --query stringArray   send an extra query parameter not declared in the spec (repeatable, key=value)

🤖 Generated with Claude Code

https://claude.ai/code/session_014TwwKSAsAGPBToNb4iUe5s