fix(cli): generated combo PATCH sends literal {id} — resolve $ref params + requestBody (#10955)

[diegosouzapw]

Closes #10955

Root cause

scripts/cli/generate-api-commands.mjs loads docs/openapi.yaml with yaml.load and never resolves $ref. The spec declares the combo path parameter via:

parameters:
  - $ref: "#/components/parameters/ResourceId"

The generator's p.in === "path" filter silently drops any $ref'd parameter — a bare { $ref } object has no .in — so every generated command on a $ref'd path param lost its --id flag and its {id} → real-id URL substitution. On top of that, PATCH /api/combos/{id} had no requestBody in the spec, so no --body was ever emitted. The result: omniroute api combos patch-api-combos-id- sent a literal PATCH /api/combos/{id} with no body → 405/mismatch upstream.

This is a pre-existing spec-wide bug, not combo-specific: #/components/parameters/ResourceId is $ref'd 20 times across the spec (providers, combos, api-keys, settings, etc.).

Fix

1. scripts/cli/generate-api-commands.mjs — added a minimal, scoped resolveParam() that only follows #/components/parameters/* refs (not a generic dereferencer — this spec never uses any other parameter-level $ref target, and a full dereferencer would be scope creep). Unsupported/unresolvable refs now throw at generation time instead of being silently dropped.
2. docs/openapi.yaml — added the missing requestBody to PATCH /api/combos/{id}, mirroring PUT's shape exactly (verified against src/app/api/combos/[id]/route.ts — PATCH delegates straight to PUT, same partial-update/merge semantics).
3. bin/cli/api-commands/combos.mjs — regenerated with the fixed generator. Diff is wiring-only: --id/--body/URL-substitution added to get/put/patch/delete combo-by-id commands (get/put were entirely missing before — same underlying bug, not new scope). No other api-commands/*.mjs file is touched in this PR; the same $ref fix will apply the next time the full build:cli-api regen runs, but that pulls in unrelated spec drift on ~15 other files that's out of scope for this issue.
4. OPENAPI_OUT_DIR env override added to the generator (mirrors the existing OPENAPI_SPEC override) purely so the new test can regenerate into a scratch directory instead of the real bin/cli/api-commands/ tree; added to the check-env-doc-sync.mjs internal-tooling allowlist next to OPENAPI_SPEC.

Tests (TDD)

tests/unit/cli-api-generator-ref-params.test.ts — RED on the untouched code, GREEN after the fix:

• generator resolves a $ref path parameter into --id and substitutes {id} in the URL (fixture spec reproducing the exact broken shape)
• generator throws on an unsupported $ref target instead of silently dropping the parameter
• the real generated bin/cli/api-commands/combos.mjs has --id and --body on the PATCH combo command

Sibling suites: tests/unit/cli-openapi-codegen.test.ts, tests/unit/cli-combo-command.test.ts — all green.

Gates run

• check-file-size.mjs — OK
• check-complexity.mjs — OK (2615 vs baseline 2774)
• check-cognitive-complexity.mjs — OK (1175 vs baseline 1223)
• npm run typecheck:core — clean
• eslint --suppressions-location config/quality/eslint-suppressions.json — clean on changed files (generated .mjs/scripts are gitignore-pattern excluded from lint, as expected)
• check-changelog-integrity.mjs — OK
• npm run check:docs-all:
  • check:docs-sync — PASS
  • check:docs-counts — 5 STRICT drifts, all pre-existing and untouched by this diff: docs/reference/PROVIDER_REFERENCE.md (346 vs 347) + 4 SVGs — this is the inherited 🔴 Release branch not green: release/v3.8.50 #9985 base-red (gh issue/nightly-release-green), not introduced here (git diff origin/release/v3.8.50 -- docs/reference/PROVIDER_REFERENCE.md docs/diagrams/ is empty)
  • check:env-doc-sync — OPENAPI_OUT_DIR resolved via allowlist; remaining 6 missing-vars are pre-existing, untouched production code (OMNIROUTE_STANDALONE_DIR, KIMI_WEB_*, OIDC_DISABLE_PASSWORD_LOGIN, etc.)
  • check:deprecated-versions — advisory (exit 0), 66 pre-existing drifts across unrelated docs
  • check:doc-links — PASS
  • check:fabricated-docs — PASS

⚠️ base-red inherited: #9985 — public-creds(copilot-m365-web), docs-sync(PROVIDER_REFERENCE)