feat: first-run DX, CI pipeline wiring & input fidelity

[jonaslagoni]

Related Issue: none (sourced from .claude/thoughts/shared/improvements/2026-07-23-2146-improvements.md, ideas 1–3; plan .claude/thoughts/shared/plans/2026-07-23-first-run-ci-input-fidelity.md)

What

Fixes three verified problem areas end to end:

1. First-run experience — config discovery matched the docs, codegen init can no longer silently produce an empty config, codegen generate warns on no-op channel generation, the internal base command is hidden, and the broken jsonschema-models example works again.
2. Test pipeline — the blackbox matrix actually runs (all config × input pairs, sharded in CI), orphaned runtime suites are wired into scripts and CI, the website workflow triggers and builds (incl. the browser bundle), and every example is smoke-tested.
3. Input-document fidelity — multi-message channels no longer drop payloads/headers, HTTP clients default their baseURL from the document's servers, and OpenAPI extraction accepts +json content types and warns (never silently drops) on skipped operations, cookie params, and webhooks.

Why

The first-run path had several silent failure modes: config file names the docs promised weren't discovered, init --no-tty without generator flags wrote generators: [] and still printed success, and generated channel barrels with no protocols were counted as output with no warning. The three-tier test pipeline had large blind spots — the blackbox suite was pinned to 1 of 23 schema files, several runtime suites ran nowhere in CI, the website workflow never triggered (wrong paths), and the browser bundle and examples had zero CI. And the input processors silently lost data: a payload-less message truncated the rest of a channel's payloads, only the first message's headers were kept, HTTP clients ignored declared servers, and OpenAPI dropped non-application/json JSON bodies and cookie/webhook constructs without a word.

Changes

First-run path

• Single CONFIG_SEARCH_PLACES constant drives both cosmiconfig discovery and the not-found error (historical 7 names keep priority; cosmiconfig-standard names appended). Docs reordered to match.
• codegen init: languages defaults to typescript; errors instead of writing empty generators; flag/answer composition fixed via shouldAskInclude; explicit --config-type wins over the prompt; new repeatable --channels-protocols flag seeds channel protocols; .gitignore entries derive from the generators actually built; warns when AsyncAPI channels end up with no protocols.
• codegen generate warns (once) when a channels generator produces no protocol functions (barrel still emitted).
• Abstract codegen base command hidden from the manifest and docs.
• examples/jsonschema-models fixed: published dependency, codegen generate script, de-duplicated config, package-lock.json, and index.ts realigned with current generated models.
• Support matrix corrected for OpenAPI channels/client in docs/generators/README.md, docs/getting-started/generators.md, and docs/inputs/openapi.md.

Input fidelity

• AsyncAPI payloads: skip-and-warn on payload-less messages instead of break (keeps every payload-bearing member; collapses to a plain schema for a single one).
• AsyncAPI headers: oneOf union across all header-bearing messages (channel-scoped id), mirroring the payloads builder; single-message output unchanged.
• HTTP client baseURL defaults to the document's first HTTP(S) server (AsyncAPI + OpenAPI); non-HTTP/relative/variable-less servers skipped with a log. Runtime context.baseUrl still overrides.
• OpenAPI: isJsonContentType accepts any +json subtype (prefers application/json); warns per operation on non-JSON-only content, per cookie parameter, and once per document with webhooks.

Test pipeline

• Blackbox unfiltered and made input-type-aware (configs only pair with schema files of matching inputType), env-overridable, with a tracked-debt KNOWN_FAILING scaffold (empty — all pairs pass); CI sharded into 4 config buckets.
• Runtime scripts/CI: test:regular + test:payload-types added to the aggregate, jsdoc.spec.ts wired in, CI matrix gains WebSocket/Organization/Payload-types (10 entries).
• Website workflow rewritten to pull_request with real paths, PR checkout, browser-bundle build, and honest install+build (dropped the nonexistent lint, dead retry, and vercel-wait steps).
• New examples-testing.yml smoke-tests every example against the packed CLI.

Docs: HTTP baseURL precedence, AsyncAPI multi-message union semantics, OpenAPI content-type support and limitations, and non-interactive init usage.

Testing

All verified locally (green):

• Unit tests — npm test (706 passing, 1 skipped)
• Build — npm run build
• Lint + typecheck — npm run lint
• Assets regenerate idempotently — npm run generate:assets (clean on second run)
• Blackbox — full matrix (214 compatible config × schema pairs) passes; ran per-config bucket via BLACKBOX_CONFIG
• Runtime tier (live Docker brokers) — http_client (114), regular (96), payload-types (270), organization (14), websocket (4), eventsource (6), nats (33), kafka (5), mqtt (8), amqp (7)

Notes

• Generated-output changes (users regenerating will see diffs): payload unions gain previously-dropped members; multi-message channels with 2+ header-bearing messages get a oneOf header union (new type name/shape); HTTP baseURL defaults to the document server instead of http://localhost:3000; OpenAPI +json-only operations now produce payload models. Single-message channels and documents without servers are unchanged. Non-output behavior changes: config discovery finds more file names (existing names keep priority), init errors instead of silently writing empty configs, and new warnings are emitted.
• Fixed one pre-existing runtime spec that Phase 19's CI wiring would have surfaced: format: time unmarshals to a string (no JS Date for a time-of-day).
• Coordination: the in-flight 2026-07-17-headers-companion-interface.md work rewrites the same header generator sites and must rebase on this branch — do not run both concurrently.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
the-codegen-project	Ready	Preview, Comment	Jul 24, 2026 12:54pm
the-codegen-project-mcp	Ready	Preview, Comment	Jul 24, 2026 12:54pm