feat(sdk): add codegen --tenant and --operator-key flags

[taitelee]

Summary

wavehouse-codegen could not generate types for a tenant of a nested settings directory. It had no way to send the ?tenant= parameter that GET /v1/ops/schema reads, and no way to send the operator key, which is the only credential the nested /v1/ops/* routes admit. --auth sends a bearer token, which gets 403 there.

• --tenant <id> (-t) is sent as ?tenant=. Without it the request names no tenant, so the server reads tenant 0. An empty value is refused client-side; any other check is the server's.
• --operator-key <key> (-k) is sent as the X-Operator-Key header. It is a separate header from --auth's Authorization: Bearer, so neither replaces the other.
• The flags are independent. --auth stays the flat-directory crtenant, and the operator key without --tenantreads tenant0`on either shape.
• Docs: the SDK reference no longer says codegen is unsupported on a nested directory and now shows how to run it against one. The options table, the SDK README
  and the --help text list both flags.

Test plan

• clients/ts/src/cli/codegen.test.ts: the URL carries ?tenant= only when the flag is set
• The operator key is sent as X-Operator-Key, with and without a bearer token, and the bearer header is left in place
• parseArgs reads both flags and their aliases, and refuses an empty --tenant
• make test-ts, Biome, tsc --noEmit, markdownlint and misspell pass
• Smoke run of the CLI: --help prints the new flags, an empclear message

Related Issues

Closes #640
Part of #583

Follow-ups

None. #527 and #528 touch the same file and are left out on purpo

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 82b74ffb-979b-4989-9047-bec7f83239a7

📥 Commits

Reviewing files that changed from the base of the PR and between 6e00558 and 036b83f.

📒 Files selected for processing (4)

• CHANGELOG.md
• clients/ts/src/cli/codegen.test.ts
• clients/ts/src/cli/codegen.ts
• docs/src/content/docs/sdk/reference.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (5)

Source excerpt: Requires Node 22 or newer — the only line this SDK is tested against; Node 18 and 20 are past upstream end-of-life.

📄 CodeRabbit inference engine (clients/ts/README.md)

Files:

• docs/src/content/docs/sdk/reference.md

Source excerpt: **Never hand-write `®` or `™` in prose.**

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• docs/src/content/docs/sdk/reference.md

Source excerpt: The TypeScript SDK (`@wavehouse/sdk` in `clients/ts/`) is the canonical client and ships from this repo.

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• clients/ts/src/cli/codegen.test.ts
• clients/ts/src/cli/codegen.ts

Source excerpt: **WH001 applies to every tracked Markdown file, with no carve-out** — `AGENTS.md`, `CHANGELOG.md`, `.github/` CI docs and `.claude/` agent prompts included.

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• docs/src/content/docs/sdk/reference.md
• CHANGELOG.md

Source excerpt: **Docs prose**: never hard-wrap Markdown — one paragraph is one line.

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Files:

• docs/src/content/docs/sdk/reference.md
• CHANGELOG.md

🧠 Learnings (1)

📓 Common learnings

Learnt from: taitelee
Repo: Wave-RF/WaveHouse

Timestamp: 2026-10-05T18:09:14.171Z
Learning: In clients/ts/src/cli/codegen.ts, operand validation must reject exact recognized CLI flags rather than all dash-leading strings. WaveHouse tenant IDs permit hyphens anywhere, and operator keys can begin with a hyphen, including base64url keys.

Learnt from: taitelee
Repo: Wave-RF/WaveHouse

Timestamp: 2026-10-05T18:09:27.610Z
Learning: WaveHouse's TypeScript streaming transport in clients/ts/src/stream/sse.ts does not follow redirects for credentialed requests. The codegen CLI in clients/ts/src/cli/codegen.ts follows the same security convention. Using redirect: "manual" allows a diagnostic that names Location; redirect: "error" produces a generic fetch failure.

Learnt from: taitelee
Repo: Wave-RF/WaveHouse

Timestamp: 2026-10-05T18:09:14.513Z
Learning: In WaveHouse, internal/api/router.go uses RequireAdmin(nil) for the nested settings directory's /v1/ops/* gate. This gate admits the operator key but rejects an admin bearer token with 403 regardless of the selected tenant. In clients/ts/src/cli/codegen.ts documentation, distinguish credential admission from tenant selection: omitting --tenant selects tenant 0 but does not make a bearer token valid for a nested directory.

🪛 ast-grep (0.45.3)

clients/ts/src/cli/codegen.test.ts

[warning] 190-190: Regular expression constructed from variable input detected. This can lead to Regular Expression Denial of Service (ReDoS) attacks if the variable contains malicious patterns. Use libraries like 'recheck' to validate regex safety or use static patterns.
Context: new RegExp(^${long} needs )
Note: [CWE-1333] Inefficient Regular Expression Complexity

(regexp-from-variable)

🪛 LanguageTool

CHANGELOG.md

[typographical] ~13-~13: Consider using an em dash in dialogues and enumerations.
Context: - **Codegen reads any tenant of a nested ...

(DASH_RULE)

🔇 Additional comments (4)

clients/ts/src/cli/codegen.ts (1)

28-51: LGTM!

Also applies to: 60-60, 64-64, 68-68, 72-75, 79-79, 89-93, 245-260

clients/ts/src/cli/codegen.test.ts (1)

91-118: LGTM!

Also applies to: 175-198, 202-209

docs/src/content/docs/sdk/reference.md (1)

156-157: LGTM!

CHANGELOG.md (1)

13-13: LGTM!

---

📝 Summary

Summary by CodeRabbit

• New Features
  • Code generation supports selecting a tenant with --tenant (-t) and authenticating with an operator key using --operator-key (-k). These options can be used independently, and bearer-token authentication remains available.
  • Without a tenant option, code generation uses tenant 0.
• Bug Fixes
  • Code generation rejects missing or empty values for value-taking options. Requests with credentials stop at redirects and report the redirect target.
• Documentation
  • Updated CLI documentation with the new options and authentication requirements.

Walkthrough

The Codegen CLI adds --tenant (-t) and --operator-key (-k). Schema requests can include a tenant query parameter, an operator-key header, and an independent bearer-token header. Credentialed requests stop at redirects and report the target.

Changes

Codegen schema access

Layer / File(s)	Summary
Parse tenant and operator-key options clients/ts/src/cli/codegen.ts, clients/ts/src/cli/codegen.test.ts	Argument parsing adds tenant and operator-key options. Value-taking flags reject missing, empty, or recognized-flag values. Tests cover defaults, aliases, combined options, and validation.
Send options to the schema endpoint clients/ts/src/cli/codegen.ts, clients/ts/src/cli/codegen.test.ts, clients/ts/README.md, docs/src/content/docs/sdk/reference.md, CHANGELOG.md	fetchSchemas adds the tenant query when its value is truthy and sends supplied credentials in separate headers. Requests with either credential use manual redirect handling and report redirect targets. Tests and documentation cover these behaviors and options.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant CodegenCLI
  participant fetchSchemas
  participant OpsSchemaEndpoint
  CodegenCLI->>fetchSchemas: Pass tenant and credential options
  fetchSchemas->>OpsSchemaEndpoint: GET /v1/ops/schema with tenant query and supplied headers

Loading

Suggested reviewers: ericandrechek

Merge Risk: 🟡 Moderate · up to 036b8

Using --operator-key with a remote HTTP endpoint can expose the key in transit. Require encrypted transport for remote credentialed requests before merging.

Security Architecture Review

Security architecture risk: 🟡 Moderate · up to 036b8

Server authorization and tenant selection remain intact, and credentialed redirects are blocked. However, the new operator-key option can send a platform-wide credential over an explicitly configured remote HTTP connection. Exploitation requires access to that unencrypted network path; the documented HTTPS example avoids this exposure.

Retained concerns

• Medium · security · inferred: The new operator-key path accepts a non-loopback HTTP URL and attaches the platform credential before sending the initial request. An attacker able to observe that unencrypted connection could capture and replay the key for broader admin and data-plane access, not merely the selected tenant's schema. Redirect rejection does not prevent initial-request exposure. This is conditional on an insecure endpoint configuration contrary to the existing TLS guidance.

Security review details

Security Blast Radius

• inferred — A captured valid operator key could authorize the platform's admin surface and unrestricted data-plane access across served tenants. The CLI's tenant selector chooses the schema response; it does not narrow the credential's authority. This maximum authority predates the PR.

Security Findings and Attack Paths

• inferred — The supported conditional attack path is a user invoking codegen with an operator key and a reachable remote HTTP URL, followed by an on-path attacker capturing the initial request header and replaying it. No initial-scheme restriction is present. No live disclosure was demonstrated, and the canonical security input contains no retained findings.

Trust Boundaries and Controls

• observed — Nested-directory ops routes admit authenticated operators rather than tenant-admin bearer identities. Tenant parsing and store selection remain server-owned. Credential-bearing requests stop at redirects, the new remote-use example uses HTTPS, and deployment guidance requires TLS for the operator secret. These controls do not enforce the scheme of the CLI's initial URL.

Hardening Proposals

• proposed — Reject non-loopback HTTP destinations before attaching an operator credential. If trusted plaintext transport must remain supported, require an explicit insecure-mode acknowledgement while preserving the documented local-development workflow.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 2 files. (2 skipped: 2…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	#640 requires codegen to send ?tenant= for the selected tenant. clients/ts/src/cli/codegen.ts parses --tenant/-t, rejects an empty value, and adds the query only when a tenant is supplied; oth…
Out of Scope Changes check	✅ Passed	The operator-key option, redirect handling, tests, and documentation changes all concern authenticated requests to /v1/ops/schema for the nested-directory use case in #640. #640 says no new credenti…
Title check	✅ Passed	The title clearly and concisely identifies the codegen flags added by the pull request.
Description check	✅ Passed	The description explains the new tenant and operator-key flags, their behavior, related documentation updates, and tests.

Full details: Docstring Coverage

Explanation

Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 2 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

✨ Simplify code

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

📚 Docs preview is live → https://dab24a05-wavehouse-docs.wave-rf.workers.dev

• Commit — 036b83f: fix(sdk): codegen refuses valueless flags and credentialed redirects
• Author — @taitelee
• Committed — 2026-10-05 11:50 (UTC-04:00)
• Deployed — 2026-10-05 15:01 EDT

[github-code-quality]

Code Coverage Overview

Languages: Go

Go

The overall line coverage in commit 036b83f in the feat/codegen-tenant-... branch remains at 93%, unchanged from commit 32e03a0 in the main branch.

---

_{Updated October 05, 2026 19:07 UTC}

[taitelee]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 4

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 64831913-9dc9-4dbd-aa29-9d54d732deeb

📥 Commits

Reviewing files that changed from the base of the PR and between 32e03a0 and 6e00558.

📒 Files selected for processing (5)

• CHANGELOG.md
• clients/ts/README.md
• clients/ts/src/cli/codegen.test.ts
• clients/ts/src/cli/codegen.ts
• docs/src/content/docs/sdk/reference.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📜 Review details

🧰 Additional context used

📓 Path-based instructions (5)

Source excerpt: Requires Node 22 or newer — the only line this SDK is tested against; Node 18 and 20 are past upstream end-of-life.

📄 CodeRabbit inference engine (clients/ts/README.md)

Files:

• docs/src/content/docs/sdk/reference.md

Source excerpt: **Never hand-write `®` or `™` in prose.**

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• docs/src/content/docs/sdk/reference.md

Source excerpt: The TypeScript SDK (`@wavehouse/sdk` in `clients/ts/`) is the canonical client and ships from this repo.

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• clients/ts/src/cli/codegen.test.ts
• clients/ts/src/cli/codegen.ts

Source excerpt: **WH001 applies to every tracked Markdown file, with no carve-out** — `AGENTS.md`, `CHANGELOG.md`, `.github/` CI docs and `.claude/` agent prompts included.

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• clients/ts/README.md
• docs/src/content/docs/sdk/reference.md
• CHANGELOG.md

Source excerpt: **Docs prose**: never hard-wrap Markdown — one paragraph is one line.

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Files:

• clients/ts/README.md
• docs/src/content/docs/sdk/reference.md
• CHANGELOG.md

🪛 LanguageTool

CHANGELOG.md

[typographical] ~13-~13: Consider using an em dash in dialogues and enumerations.
Context: - **Codegen reads any tenant of a nested ...

(DASH_RULE)

[taitelee]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.