Support required cookies, bodies, and forms in RouteBuilder

[pmcelhaney]

Summary

• add immutable cookies() and form() methods to RouteBuilder
• validate required OpenAPI cookies, Swagger 2 body and formData parameters, and OpenAPI 3 request bodies
• merge encoded cookies with existing Cookie headers and serialize URL-encoded or text-only multipart forms
• make body() and form() last-method-wins request entities
• align help, inspection, missing-input diagnostics, REPL completions, docs, tests, and package changesets

Binary and file multipart parts remain intentionally unsupported.

Verification

• client tests: 4 suites, 80 tests passed
• REPL tests: 1 suite, 57 tests passed
• full unit suite: 65 suites, 961 tests, and 127 snapshots passed
• build, typecheck, and lint passed
• packed @counterfact/client consumer and the changed developer black-box journey passed
• release preflight passed, including package boundaries, packaging dry runs, isolated package closures, and changeset validation

Manual acceptance tests

• In the REPL, confirm an OpenAPI 3 JSON operation with a required request body is not ready until body() is called, then sends successfully.
• Confirm a required cookie is satisfied by either a case-insensitive Cookie header or cookies(), and that cookies() merges percent-encoded pairs with an existing header.
• Confirm a Swagger 2 operation with required formData fields reports missing keys and sends URL-encoded data after matching form() values are supplied.
• Confirm a multipart-only form operation sends text fields with a generated multipart boundary and does not claim support for binary or file parts.
• Confirm calling body() after form(), or form() after body(), sends only the last entity while existing path, query, and header behavior remains unchanged.

Repository learning check

• Learning found: Yes
• Guidance updated: Yes
• Updated file(s): .github/skills/counterfact-maintenance/SKILL.md
• Rationale: OpenAPI-aware request-builder changes need coordinated catalog, immutable state, diagnostics, documentation, serialization, and real-network verification, including explicit precedence for competing request entities.

[Copilot]

🟡 Changes recommended

Required-body readiness can be incorrectly satisfied by .body(undefined), and the changeset currently marks a breaking public API change as a patch.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR expands the RouteBuilder API to support immutable cookies() and form() inputs, validates required cookie/body/form inputs across OpenAPI/Swagger variants, and updates serialization + UX (help output, REPL completions, diagnostics) to match the new capabilities.

Changes:

• Add cookies + form fluent APIs, required-input validation (OpenAPI 2 + OpenAPI 3), and “last entity wins” behavior between body() and form().
• Implement cookie-header merging and form serialization (URL-encoded by default; text-only multipart when multipart is the sole declared form type).
• Update REPL completions, black-box journey, docs, and tests; adjust HTTP message printing to preserve multipart bodies.

File summaries

File	Description
test-black-box/test_developer_journey.py	Extends the REPL developer journey to assert required request body behavior.
test-black-box/features/developer_journey.feature	Adds a new Gherkin step for required pet body readiness.
packages/repl/test/repl.test.ts	Updates completion expectations to include cookies( and form(.
packages/repl/src/repl.ts	Adds cookies( and form( to the REPL route-builder completion set.
packages/counterfact/test/fixtures/openapi/swagger2.yaml	Adds a Swagger 2 fixture covering required formData.
packages/counterfact/test/fixtures/openapi/multipart.yaml	Adds an OpenAPI 3 fixture for required multipart text-only form bodies.
packages/counterfact/docs/features/route-builder.md	Documents cookies/forms, required-input semantics, entity precedence, and multipart display.
packages/client/test/route-catalog.test.ts	Adds coverage for Swagger 2 consumes inheritance behavior.
packages/client/test/route-builder.test.ts	Adds extensive unit coverage for required cookie/body/form inputs, help output, and inspection output.
packages/client/test/route-builder.integration.test.ts	Adds socket-level integration tests for cookie merge + form serialization + precedence.
packages/client/test/raw-http-client.test.ts	Ensures request printing shows full multipart bodies including the closing boundary.
packages/client/test/package/client-consumer-smoke.mjs	Updates consumer smoke expectations for help() writing to console.
packages/client/src/route-catalog.ts	Extends catalog metadata to include consumes + OpenAPI 3 requestBody.
packages/client/src/route-builder.ts	Implements cookies/forms, required-input validation, entity precedence, and serialization.
packages/client/src/raw-http-client.ts	Fixes HTTP head/body splitting to preserve multipart bodies in printed output.
packages/client/src/index.ts	Exports the new RouteRequestBody type.
packages/client/README.md	Updates public docs for new methods and changed help() behavior.
package.json	Adds generator scripts for the new OpenAPI fixtures.
.github/skills/counterfact-maintenance/SKILL.md	Captures durable guidance for multipart display splitting + aligned request-builder changes.
.changeset/clear-multipart-display.md	Records the multipart display + help-output behavioral change for release notes.
.changeset/bright-forms-build.md	Records the route-builder cookies/body/form support + REPL completion changes for release notes.

Review details

• Files reviewed: 21/21 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.