@redocly/client-generator 0.3.7 → 0.4.0

package/eject-assets/skills/client-generators/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: client-generators
+description: Write or change a Redocly client generator — the API model, the language-neutral helper toolkit, and the edit → regenerate → diff loop.
+---
+
+# Writing custom client generators
+
+A generator is a plain module: `(input) => GeneratedFile[]`. It receives the
+language-agnostic API model and returns files — in ANY output language. It runs
+in the same pass as the built-ins; select it by path in `redocly.yaml`:
+
+```yaml
+client:
+  generators: [typescript, ./generators/my-generator.mjs]
+```
+
+## The contract
+
+```js
+/** @type {import('@redocly/client-generator').CustomGenerator} */
+export default {
+  name: 'my-generator',
+  run({ model, output, outputMode, emit }) {
+    return [{ path: output.path.replace(/\.ts$/, '.mine.txt'), content: '…' }];
+  },
+  // Optional: one idiomatic call snippet per operation for docs (x-codeSamples),
+  // collected into an overlay file when `client.codeSamples: true` is set.
+  sample(operation, { model, emit }) {
+    return { lang: 'python', source: '…' };
+  },
+  // Optional: the reference page for what `run` emits, written when `client.docs` (or
+  // --docs) is on. Same `{ path, content }` shape as `run`; `renderReferencePage` gives
+  // the standard layout and takes `sample` for its snippets. A generator documents itself.
+  docs({ model, output, emit }) {
+    return [{ path: output.path.replace(/\.ts$/, '.mine.md'), content: '…' }];
+  },
+};
+```
+
+## Declaring options
+
+A generator that needs configuration declares it as a schema; `run` then receives
+`options` already validated, with defaults applied:
+
+```js
+export default {
+  name: 'permissions-matrix',
+  options: {
+    type: 'object',
+    properties: { groupBy: { enum: ['tag', 'path'], default: 'tag' } },
+    additionalProperties: false,
+  },
+  run({ model, output, options }) {
+    return [
+      { path: output.path.replace(/\.ts$/, '.permissions.md'), content: render(options.groupBy) },
+    ];
+  },
+};
+```
+
+Users set them per generator name:
+
+```yaml
+client:
+  generators: [typescript, ./generators/permissions-matrix.mjs]
+  options:
+    permissions-matrix:
+      groupBy: path
+```
+
+The supported subset is a top-level `type: 'object'` with `properties`, `required`, and
+`additionalProperties`; each property is a scalar (`string`/`number`/`boolean`), an
+`enum`, or an array of scalars, and may carry a `default` and a `description`. Don't
+validate options inside `run` — an unknown key, a wrong type, a value outside an `enum`,
+or a missing `required` key already fails generation before `run` is called.
+
+Rules: output is deterministic (same description → same bytes); never add
+dependencies to the generated client; **never hand-edit generated output** —
+edit this generator and regenerate. Emitted file paths must stay inside the
+`--output` directory (subdirectories are fine) — escapes are rejected.
+Optionally declare `requiresGenerator` — the `@redocly/client-generator` version
+range you wrote this against (`'^1.2.0'`, `'~1.2.0'`, `'>=1.2.0'`, or an exact
+version). A CLI outside the range then fails with the fix path instead of feeding
+your generator an unexpected model shape. Ejected generators carry it
+automatically; hand-written ones without it are taken as current.
+
+## The model (IR)
+
+`model.services[].operations[]` — each operation carries `name`, `specName`,
+`method`, `path`, `tags`, `pathParams`/`queryParams`/`headerParams`/`cookieParams`,
+`requestBody`, `successResponses`/`errorResponses` (each with a `schema`), and
+`security`. `model.schemas` holds the named schemas. Every schema is a
+discriminated union on `kind`: `scalar`, `array`, `object`, `record`, `ref`,
+`literal`, `enum`, `union` (optionally with a discriminator), `intersection`
+(allOf), `null`, `unknown`, `omit`.
+
+## Helpers (import from '@redocly/client-generator')
+
+| Helper                                                  | Use                                                                                                                              |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `flattenAllOf(schema, model)`                           | The merged property view of allOf compositions — languages without intersection types render this.                               |
+| `deref(schema, model)`                                  | Follow a `ref` chain to the schema it names (cycle-guarded).                                                                     |
+| `jsonSuccessSchema(op)` / `sseResponse(op)`             | The primary JSON success schema; the `text/event-stream` response when the operation streams.                                    |
+| `isMultipartBody(op)`                                   | Whether the request body is multipart.                                                                                           |
+| `serverUrlParts(server)`                                | A server-URL template as literal/variable parts, ready for any concatenation syntax.                                             |
+| `securityRequirements(op, model)`                       | The operation's security as OR-alternatives of AND-sets, denormalized against the declared schemes.                              |
+| `paginationItemSchema(pageSchema, itemsPointer, model)` | The raw element schema behind a pagination rule's `items` pointer — a `ref` element keeps its name.                              |
+| `discriminatorCases(schema, model)`                     | `{ property, cases }` dispatch table for discriminated unions.                                                                   |
+| `isNullable(schema)` / `unwrapNullable(schema)`         | Detect and strip `null` union members (`Optional[T]`, pointers, `Option<T>`).                                                    |
+| `enumValues(schema)`                                    | Values plus SCREAMING_SNAKE member-name suggestions.                                                                             |
+| `headerCoerceType(schema, model)`                       | Response-header coerce hint (`integer`/`number`/`boolean`/`string`) through refs, nullables, and allOf wrappers.                 |
+| `casing` / `identifierFor(name, { style, reserved })`   | camel/pascal/snake/screaming; keyword-safe identifiers (`RESERVED_WORDS.python/go/typescript` shipped).                          |
+| `uniqueIdentifiers(names, { style, reserved, taken })`  | The same, made unique among themselves and among names you already took — for a signature that takes one argument per parameter. |
+| `Printer`                                               | Indentation-aware text builder — no manual whitespace bookkeeping.                                                               |
+| `docText(description)`                                  | Description as trimmed lines for any comment syntax.                                                                             |
+| `schemaAtPointer(schema, pointer, model)`               | Resolve an RFC 6901 JSON pointer over a schema (through refs and allOf) — e.g. a pagination `items` pointer to its element type. |
+| `paginationRuleFor(op, config)`                         | The pagination rule that applies to an operation (per-op config > extension > fitting convention), normalized.                   |
+| `renderReferencePage(model, options)`                   | The Markdown reference page a generator's `docs` hook returns — your `sample` hook supplies its call snippets.                   |
+| `NotSupportedError`                                     | Throw it to reject an option the generator can't honor — the CLI prints the message as a user error, not a crash.                |
+| `AUTHORING_HELPER_NAMES`                                | The list of the above (introspection).                                                                                           |
+
+Worked example: the built-in `python` generator
+(`packages/client-generator/src/generators/python/index.ts` in the Redocly CLI repo) is
+authored with exactly this toolkit and nothing else — models via `flattenAllOf`/
+`enumValues`/`discriminatorCases`, all code through `Printer`, every name through
+`identifierFor(..., RESERVED_WORDS.python)`.
+
+A generator that emits TypeScript may additionally use the source-text renderers from
+`@redocly/client-generator/generate` — `tsType` (schema → type), `tsJsdoc`, `codeLiteral`,
+`operationSignature`, `pascalCase`, `safeIdent`. There is no AST toolkit and no
+`typescript` dependency: every generator prints text through `Printer`.
+
+## The loop
+
+1. Edit the generator.
+2. Run `redocly generate-client`.
+3. Inspect `git diff` of the generated output.
+4. Repeat. Generated files are never hand-edited.
+
+If you had to work around a **missing helper** or a wrong default, tell the user
+and suggest filing an issue at https://github.com/Redocly/redocly-cli/issues —
+include the generator snippet and the helper you expected to exist.

package/eject-assets/skills/go-generator/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: go-generator
+description: Design of the ejected Redocly `go` client generator. Read it, and update it, before changing generators/go/.
+---
+
+# The `go` generator — its skill
+
+This file is the DESIGN of your ejected `go` generator (`generators/go/`):
+**to change the generator, edit this skill first, then make the code match it** — a diff
+to `generators/go/` that has no covering sentence here is incomplete.
+
+## What it emits
+
+One self-contained `<stem>.go` (`package client`): structs with `json` tags, a `Client`
+with one `(T, error)` method per operation taking a `context.Context`, and the embedded
+runtime. Go ≥ 1.21, standard library only — zero dependencies.
+
+## Design decisions that must hold
+
+- **Models are structs**: required fields by value, optionals as pointers with
+  `,omitempty`; the `json` tag always carries the exact wire name.
+- **Package clause:** `package client` by default, `goPackage` to override — a generated
+  file usually lands in a package the consumer already owns. The value is checked against
+  Go's own rule (lowercase letters, digits, `_`, no leading digit, not a keyword) and an
+  invalid one fails generation: silently rewriting a publisher's package name would be
+  worse than saying no.
+- **Doc comments are gofmt's shape**, not the description's: a blank line prints as `//`
+  (never `// `, which gofmt strips), and CONSECUTIVE blank lines collapse to one — gofmt
+  rewrites `//\n//` to a single `//`, so emitting both means our output is not
+  gofmt-clean. Descriptions with a double blank line are common in real specs.
+- **Every parameter is its own argument, so their names share one namespace** with the
+  arguments the method declares itself (`ctx`, `body`, `params`, and the receiver). Build them with
+  `uniqueIdentifiers(..., { taken: … })`: OpenAPI lets one operation use a name in two
+  locations (`id` in the path AND in the query), and Go rejects a duplicate parameter. The
+  wire name is untouched, so the request is unchanged.
+- **Naming:** exported PascalCase via `identifierFor` + an `N` prefix for digit-leading
+  names (`3ds` → `N3ds` — an `_`-prefixed field is unexported and invisible to
+  `encoding/json`); `+1`/`-1` become `Plus1`/`Minus1`.
+- **Enums** are typed consts (`type Status string` + `StatusInProgress Status = …`);
+  **discriminated unions** are `type X = any` plus a generated `UnmarshalX([]byte)`
+  dispatcher; **allOf** is flattened.
+- **Errors:** `(T, error)` returns ARE the error mode — `errorMode` does not change the
+  output (the generator declares `errorModes: ['throw']`, so `result` fails fast).
+  Non-2xx → `*APIError`; timeouts → `*TimeoutError`.
+- **Dates:** `dateType: Date` maps `format: date-time` to `time.Time` (encoding/json
+  handles RFC 3339 natively) and `date` to the runtime's `Date` wrapper, which
+  marshals as `2006-01-02`. Query values format explicitly, never via `String()`.
+- **Response headers:** an operation that DECLARES success-response headers gains a
+  `<Op>WithHeaders(ctx, …) (T, <Op>Headers, error)` variant; `<Op>Headers` is a
+  generated struct with pointer fields (nil when absent or unparsable), coerced to
+  int64/bool/string. Operations without declared headers get no variant, and the
+  base method stays `(T, error)`.
+- **Servers:** when the description declares servers, one `<Name>URL(...)` function per
+  server is emitted (named from the server description); server VARIABLES become string
+  parameters (Go has no defaults — the doc comment states the spec default), so templated
+  base URLs need no manual string building. The client's baked default stays `servers[0]`
+  with variable defaults substituted.
+- **Parity surface:** auth, retries with `Retry-After` + jittered backoff, per-attempt
+  `context.WithTimeout`, idempotency keys, middleware, pagination (`<Op>Pages`/`<Op>Items`
+  as `func(yield func(T, error) bool)` — `range`-over-func needs Go ≥ 1.23; 1.21 calls
+  them with a callback), SSE, multipart.
+- **The EMITTED FILE is gofmt-clean, not just the runtime.** `gofmt -l` on generated
+  output must print nothing, so the download is idiomatic as-is. The emitter earns that
+  deterministically, without shelling out to `gofmt`:
+  - `alignGoColumns` pads columns the way gofmt's tabwriter does — struct field types and
+    tags, `const`/`var` types and `=`, and map-literal values — within each contiguous run.
+    A line starting with a Go KEYWORD is a statement, never a declaration, and must never
+    be padded (`case "x":` is not a field).
+  - `case` sits at its `switch`'s own indent, so the switch body is not emitted as an
+    indented block.
+  - At most one blank line between declarations, none at end of file, and a blank line
+    inside a doc comment is `//` — never `// ` with a trailing space.
+    A change here is verified by the `gofmt -l` bar in the unit suite, at cafe AND
+    large-description scale.
+- The runtime is hand-written in `runtime/runtime.go` in this folder (gofmt-clean, `go vet`-clean)
+  and embedded at prepare time.
+  Under `--runtime module` it is written as a same-package `runtime.go` beside the client,
+  whose import block then lists only the packages its own body uses.
+- Authored ONLY with the neutral toolkit — the dogfooding guard fails otherwise.
+
+- **It documents itself.** With `client.docs` (or `--docs`), the `docs` hook writes
+  `<stem>.go.md`: the security schemes, then one section per operation with its parameters,
+  body, response type, and behavior notes. The call snippets come from this generator's own
+  `sample` hook, so the page can only show the syntax of the SDK beside it, and the layout
+  comes from `renderReferencePage` in the authoring toolkit — reachable from an ejected copy
+  through `@redocly/client-generator`. Pagination on the page is decided by
+  `paginationRuleFor`, the same helper this generator resolves pagination with.
+
+## The modify loop
+
+1. Edit this skill: state the new behavior or decision.
+2. Make `generators/go/` match it.
+3. Run `redocly generate-client` and inspect the `git diff` of the generated output —
+   generated files are never hand-edited.
+
+Newer built-in versions merge in with `redocly eject-generator go --update`.

package/eject-assets/skills/mock-generator/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: mock-generator
+description: Design of the ejected Redocly `mock` client generator. Read it, and update it, before changing generators/mock/.
+---
+
+# The `mock` generator — its skill
+
+This file is the DESIGN of your ejected `mock` generator (`generators/mock/`):
+**to change the generator, edit this skill first, then make the code match it** — a diff
+to `generators/mock/` that has no covering sentence here is incomplete.
+
+## What it emits
+
+A standalone MSW module: `create<Name>()` data factories, `<op>Handler()` /
+`<op>ErrorHandler(status, body?)` request handlers, and a `handlers` array.
+
+## Design decisions that must hold
+
+- **Two data modes:** `mockData: static` bakes deterministic samples from the schema
+  (examples/defaults first); `faker` emits `faker.*` calls with a seed (`mockSeed`) so
+  runs are reproducible.
+- **Interpolated identifiers are gated** (`codeIdent`): an operation name or method
+  reaching a code position is validated, never trusted, even though the pipeline
+  sanitizes upstream.
+- Handlers are opt-in overrides: `<op>ErrorHandler` is NOT in `handlers`.
+- The module references the sdk's TYPES only — never its runtime.
+
+## The stage files
+
+`render.ts` assembles the module (factories, handlers, the `handlers` array);
+`sample.ts` bakes deterministic sample values from the schema, `values.ts` renders the
+data trees, and `faker.ts` emits the faker-mode expressions. `index.ts` is the entry.
+
+## Ejecting it
+
+`redocly eject-generator mock` copies this generator's TypeScript source folder to
+`generators/mock/`, exactly as we wrote it, importing `@redocly/client-generator`,
+`@redocly/client-generator/printers/typescript`, and `@redocly/openapi-core`. Running a
+`.ts` generator uses Node's type stripping (Node 22.18, 23.6, or newer); newer built-in
+versions merge in per file with `--update`. Change the data strategy, the handler shape,
+or the factory surface, and regenerate.
+
+## The modify loop
+
+1. Edit this skill: state the new behavior or decision.
+2. Make `generators/mock/` match it.
+3. Run `redocly generate-client` and inspect the `git diff` of the generated output —
+   generated files are never hand-edited.
+
+Newer built-in versions merge in with `redocly eject-generator mock --update`.

package/eject-assets/skills/php-generator/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: php-generator
+description: Design of the ejected Redocly `php` client generator. Read it, and update it, before changing generators/php/.
+---
+
+# The `php` generator — its skill
+
+This file is the DESIGN of your ejected `php` generator (`generators/php/`):
+**to change the generator, edit this skill first, then make the code match it** — a diff
+to `generators/php/` that has no covering sentence here is incomplete.
+
+## What it emits
+
+One self-contained `<stem>.php`: promoted-constructor model classes, a `Client` with one
+typed method per operation, and the embedded runtime. PHP ≥ 8.1, HTTP over the curl
+extension — zero Composer dependencies. The namespace derives from the API title
+(`identifierFor(title, pascal)` — e.g. `CafeOrders`).
+
+## Design decisions that must hold
+
+- **Models are `final class`es** with constructor property promotion, required parameters
+  first, optionals nullable `= null`. Hydration is compile-time generated per class:
+  `fromArray(array $data): self` and `toArray(): array` (wire names inline; nulls
+  skipped on serialize) — no reflection. `omit` schemas hydrate/serialize through their
+  base class. A property or response typed as a DISCRIMINATED union hydrates through the
+  union's `unmarshalX` dispatcher, so consumers can narrow with `instanceof`;
+  undiscriminated unions stay raw arrays.
+- The `Client` class is NOT `final` — PHP test suites mock concrete classes
+  (`createMock(Client::class)`), and `final` would force a wrapper interface on every
+  consumer. Model classes stay `final`.
+- **Every parameter is its own argument, so their names share one namespace** with the
+  arguments the method declares itself (`$body`, `$headers`, `$idempotencyKey`). Build them with
+  `uniqueIdentifiers(..., { taken: … })`: OpenAPI lets one operation use a name in two
+  locations (`id` in the path AND in the query), and PHP rejects a redefined parameter outright. The
+  wire name is untouched, so the request is unchanged.
+- **Naming:** classes PascalCase, properties/methods camelCase via
+  `identifierFor(..., RESERVED_WORDS.php)`; reserved words get a trailing underscore.
+- **Enums** are native backed enums (string/int); other scalars stay aliases.
+  **Discriminated unions** are `match`-based `unmarshalX(array $data)` dispatchers;
+  **allOf** is flattened.
+- **Unions keep their types where PHP 8.1 can express them.** A union of scalars, enums,
+  classes, or arrays becomes a native union type (`int|string`, `PromotionType|array`)
+  rather than collapsing to `mixed` — rich list filters are the common case and losing
+  their types loses the point of a typed SDK. It falls back to `mixed` only when a member
+  has no PHP type of its own (an inline object, an intersection, `unknown`), because
+  `mixed` cannot appear inside a union. Nullability is expressed as `|null` in a union
+  (PHP forbids mixing `?` with `|`) and `?T` for a single type.
+- **Errors:** exceptions ARE the error mode (`ApiError`/`TimeoutError` extend
+  `\RuntimeException`); `errorMode` does not change the output (the generator declares
+  `errorModes: ['throw']`, so `result` fails fast).
+- **Dates:** `dateType: Date` types `format: date`/`date-time` as
+  `\DateTimeImmutable`; hydration is `new \DateTimeImmutable(...)` and serialization
+  formats with `\DateTimeInterface::ATOM` (date-time) or `'Y-m-d'` (date), including
+  for query parameters.
+- **Method arguments:** required path params positional, JSON body next, optional query
+  params as nullable NAMED arguments, then `?array $headers`, and `?string
+$idempotencyKey` on mutating methods.
+- **Non-JSON success bodies** (PDFs, images, octet streams) return the raw body as
+  `string` — a binary download must never degrade to `void`.
+- **PHPDoc carries what the signature cannot.** PHP's `array` and `\Generator` erase their
+  element type, so a docblock states it: `@return Customer[]` for collection returns and
+  `@return \Generator<int, Customer>` on `<op>Pages()`/`<op>Items()`. Static analysis and
+  readers go by these; a hydrated return with no annotation looks untyped.
+- **Response headers:** an operation that DECLARES success-response headers gains a
+  `<op>WithHeaders()` variant returning an `Envelope` (`data`, `headers` — coerced to
+  int/bool/string with camelCase keys, absent/unparsable values omitted — and `status`).
+  Operations without declared headers get no variant, and the base method stays
+  body-only (PHP cannot vary a return type on a flag).
+- **Servers:** when the description declares servers, a `Servers` class is emitted with
+  one static method per server; server VARIABLES become named string arguments defaulting
+  to the spec's defaults (`Servers::production(organizationId: 'org_x')`), so templated
+  base URLs need no manual string building. The client's baked default stays `servers[0]`
+  with variable defaults substituted.
+- **Parity surface:** auth, retries with `Retry-After` + jittered backoff, per-attempt
+  curl timeouts, middleware callables, pagination (`<op>Pages()` / `<op>Items()` as
+  `\Generator`s), SSE (`iterSse` over a curl_multi pump), multipart.
+- The runtime is hand-written in `runtime/runtime.php` in this folder (`php -l`-clean) and embedded
+  at prepare time. `curl_close` is never called (deprecated since PHP 8.5, no-op since 8.0).
+  Under `--runtime module` it is written as a `runtime.php` the client `require_once`s,
+  with its namespace rewritten to the client's so one namespace spans both files.
+- Authored ONLY with the neutral toolkit — the dogfooding guard fails otherwise.
+
+## Migrating from a service-based SDK
+
+- Per-resource services (`$client->customers()->get($id)`) map to flat methods named
+  after operationIds (`$client->getCustomer($id)`); optional query params keep their
+  named-argument style (`filter:`, `sort:`, `limit:`).
+- Collection wrappers exposing pagination RESPONSE HEADERS (`getTotalItems()`,
+  `getLimit()`) map to the `<op>WithHeaders()` envelope
+  (`->headers['paginationTotal']`); plain iteration maps to `<op>Items()` /
+  `<op>Pages()` generators.
+- Dedicated validation-exception classes exposing field errors map to
+  `catch (ApiError $e)` + `$e->status === 422` + the decoded `$e->body`.
+- Session/bearer token flows map to `auth: ['bearer' => $tokenProvider]` with a
+  callable — resolved per request, so refresh needs no client rebuild.
+
+- **It documents itself.** With `client.docs` (or `--docs`), the `docs` hook writes
+  `<stem>.php.md`: the security schemes, then one section per operation with its parameters,
+  body, response type, and behavior notes. The call snippets come from this generator's own
+  `sample` hook, so the page can only show the syntax of the SDK beside it, and the layout
+  comes from `renderReferencePage` in the authoring toolkit — reachable from an ejected copy
+  through `@redocly/client-generator`. Pagination on the page is decided by
+  `paginationRuleFor`, the same helper this generator resolves pagination with.
+
+## The modify loop
+
+1. Edit this skill: state the new behavior or decision.
+2. Make `generators/php/` match it.
+3. Run `redocly generate-client` and inspect the `git diff` of the generated output —
+   generated files are never hand-edited.
+
+Newer built-in versions merge in with `redocly eject-generator php --update`.

package/eject-assets/skills/python-generator/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: python-generator
+description: Design of the ejected Redocly `python` client generator. Read it, and update it, before changing generators/python/.
+---
+
+# The `python` generator — its skill
+
+This file is the DESIGN of your ejected `python` generator (`generators/python/`):
+**to change the generator, edit this skill first, then make the code match it** — a diff
+to `generators/python/` that has no covering sentence here is incomplete.
+
+## What it emits
+
+One self-contained `<stem>.py`: typed dataclass models, a sync `Client` and an async
+`AsyncClient`, and the embedded runtime. Python ≥ 3.9; the only dependency is
+[httpx](https://www.python-httpx.org/) (`pip install httpx`).
+
+## Design decisions that must hold
+
+- **The file name is an importable module name.** The `--output` stem follows the TypeScript
+  convention (`openapi.client.ts`), and `openapi.client.py` cannot be imported by name — nor
+  can hyphens or a leading digit. The stem is converted with
+  `identifierFor(stem, snake)`, so `rebilly-core.client.ts` emits
+  `rebilly_core_client.py` and `import rebilly_core_client` just works.
+
+- **Models are dataclasses by default**, required fields first (a dataclass constraint),
+  optionals `Optional[T] = None`. Wire names live in a `_field_map: ClassVar[Dict[str, str]]`;
+  decode/encode is reflective (`_decode.py`, `get_type_hints`) — no per-model codecs.
+- **`models: pydantic` emits `BaseModel` classes instead**, for the FastAPI-shaped half of
+  the ecosystem that expects them. A wire name becomes `Field(alias=…)` with
+  `populate_by_name=True`, so `_field_map` is not emitted in this mode — the alias is the
+  mapping. Everything else is unchanged: the same class names, the same field names, the
+  same `Optional[T] = None`, the same enums and union aliases, the same client and runtime.
+  Switching modes must not change a call site.
+- **A discriminated union carries its discriminator into the pydantic annotation.** The
+  decoder hands a whole object tree to `model_validate`, so a union nested in a model is
+  resolved by pydantic and never reaches the `DISCRIMINATORS` table that dataclass mode
+  walks. Pydantic resolves it correctly from `Annotated[Union[...], Field(discriminator=…)]`,
+  which it accepts only when every member types that property as a `Literal` — and the
+  mapping already pins one value per member, so the members get `Literal["cat"]`. Such a
+  union registers no table entry: pydantic owns it at every depth, and the `Literal` makes
+  the decoder's member probe exact. A union whose members never declare the property keeps
+  the plain `Union` and the table entry, and pydantic then matches nested members its own
+  way — the description is what has to change there.
+- **One runtime serves both model modes.** `_decode.py` dispatches on the target: a class
+  with `model_validate` is validated by pydantic, a dataclass is hydrated reflectively, and
+  `encode` mirrors that with `model_dump(by_alias=True, exclude_none=True, mode="json")`.
+  A second runtime variant per mode would double the surface that has to stay in step, and
+  pydantic's `ValidationError` already subclasses `ValueError`, so union member probing
+  needs no new except clause.
+- **`models: pydantic` adds a dependency, and the header says so.** The default mode keeps
+  httpx as the only requirement; the pydantic header asks for both. A mode that quietly
+  needed a package the file never named would fail at import with nothing to act on.
+- **Every parameter is its own argument, so their names share one namespace** with the
+  arguments the method declares itself (`body`, `headers`, `timeout`, `retry`, `idempotency_key`). Build them with
+  `uniqueIdentifiers(..., { taken: … })`: OpenAPI lets one operation use a name in two
+  locations (`id` in the path AND in the query), and a `def` that declared one name twice is a `SyntaxError`. The
+  wire name is untouched, so the request is unchanged.
+- **Naming:** fields/methods snake*case via `identifierFor(..., RESERVED_WORDS.python)`;
+  reserved words get a trailing underscore (`class*`); `+1`/`-1`become`plus_1`/`minus_1`.
+- **Enums** are `class X(str, Enum)` with SCREAMING members; **unions** are `Union[...]`
+  aliases. A DISCRIMINATED union registers its dispatch table in the runtime's
+  `DISCRIMINATORS` registry (`DISCRIMINATORS[Pet] = ("petType", {"cat": Cat, ...})`),
+  and `decode()` routes through it — `isinstance` narrowing works on decoded members.
+  Undiscriminated unions decode by trying each member in order (the first that
+  hydrates wins — see `_decode.py`). **allOf** is flattened via `flattenAllOf`.
+- **Auth keys match the other languages.** `auth={"apiKey": {...}}` is the documented key —
+  the same spelling TypeScript and PHP use, and the same as the scheme kind — with
+  `api_key` accepted as an alias so a snake_case config keeps working.
+- **Errors:** `errorMode` maps to raising `ApiError` (default) or returning a `Result`
+  dataclass — the only generator with both modes outside TypeScript.
+- **Dates:** `dateType: Date` annotates `format: date-time` as `datetime` and `date` as
+  `date`; `_decode.py` parses ISO strings into them and `encode()` writes `isoformat()`
+  back. The default (`string`) keeps the wire shape.
+- **Response headers:** an operation that DECLARES success-response headers gains a
+  `<op>_with_headers()` variant (sync and async) returning `Envelope[T]` — `data`,
+  `headers` (coerced to int/bool/str with snake_case keys; absent/unparsable values
+  omitted), and the raw `response`. Operations without declared headers get no
+  variant, and the base method stays body-only.
+- **Servers:** when the description declares servers, a `Servers` class is emitted with
+  one static method per server; server VARIABLES become keyword arguments defaulting to
+  the spec's defaults (`Servers.production(organization_id="org_x")`), so templated base
+  URLs need no manual string building. The client's baked default stays `servers[0]`
+  with variable defaults substituted.
+- **Parity surface:** auth (bearer/basic/apiKey), retries with `Retry-After` + jittered
+  backoff, timeouts, idempotency keys, middleware, pagination (`<op>_pages()` /
+  `<op>_items()` + `aiter` mirrors), SSE (`iter_sse`/`aiter_sse`), multipart.
+- The runtime is hand-written in `runtime/*.py` in this folder and embedded as strings at prepare
+  time — generator code never builds runtime logic from templates.
+  Under `--runtime module` the same sources are written as sibling `_*.py` files instead
+  (package-relative imports become sibling imports; the client star-imports each module).
+- Authored ONLY with the neutral toolkit (`Printer`, naming, schema, pagination helpers) —
+  the dogfooding guard fails otherwise.
+
+- **It documents itself.** With `client.docs` (or `--docs`), the `docs` hook writes
+  `<stem>.python.md`: the security schemes, then one section per operation with its parameters,
+  body, response type, and behavior notes. The call snippets come from this generator's own
+  `sample` hook, so the page can only show the syntax of the SDK beside it, and the layout
+  comes from `renderReferencePage` in the authoring toolkit — reachable from an ejected copy
+  through `@redocly/client-generator`. Pagination on the page is decided by
+  `paginationRuleFor`, the same helper this generator resolves pagination with.
+
+## The modify loop
+
+1. Edit this skill: state the new behavior or decision.
+2. Make `generators/python/` match it.
+3. Run `redocly generate-client` and inspect the `git diff` of the generated output —
+   generated files are never hand-edited.
+
+Newer built-in versions merge in with `redocly eject-generator python --update`.

package/eject-assets/skills/swr-generator/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: swr-generator
+description: Design of the ejected Redocly `swr` client generator. Read it, and update it, before changing generators/swr/.
+---
+
+# The `swr` generator — its skill
+
+This file is the DESIGN of your ejected `swr` generator (`generators/swr/`):
+**to change the generator, edit this skill first, then make the code match it** — a diff
+to `generators/swr/` that has no covering sentence here is incomplete.
+
+## What it emits
+
+React SWR hooks over the sdk's exported operation functions: `use<Op>()` with a
+`<op>Key()` key factory for queries, `useSWRMutation` for mutations.
+
+## Design decisions that must hold
+
+- **Wraps the sdk's functions** — it never re-implements requests, so it requires `typescript`
+  and is throw-mode only.
+- **Keys are exported factories** so consumers can invalidate precisely.
+- **`envelope` is excluded** from hook options (`Omit<RequestOptions, "envelope">`) and
+  stripped from the forwarded call: cached data is always the plain body.
+- **Skips what it cannot wrap** — SSE operations and `<Op>Variables` name collisions —
+  with a warning naming each one, never silently.
+
+## The stage files
+
+`render.ts` holds the whole hook renderer; `index.ts` is the entry. The wrappable-operation
+policy and the sdk calling convention come from the typescript generator's published
+contract (`@redocly/client-generator/contracts/typescript`), so this generator cannot
+drift from the sdk it wraps.
+
+## Ejecting it
+
+`redocly eject-generator swr` copies this generator's TypeScript source folder to
+`generators/swr/`, exactly as we wrote it, importing `@redocly/client-generator`,
+`@redocly/client-generator/printers/typescript`, and
+`@redocly/client-generator/contracts/typescript`. Running a `.ts` generator uses Node's
+type stripping (Node 22.18, 23.6, or newer); newer built-in versions merge in per file
+with `--update`. Change the hook shape or the key strategy, and regenerate.
+
+## The modify loop
+
+1. Edit this skill: state the new behavior or decision.
+2. Make `generators/swr/` match it.
+3. Run `redocly generate-client` and inspect the `git diff` of the generated output —
+   generated files are never hand-edited.
+
+Newer built-in versions merge in with `redocly eject-generator swr --update`.

package/eject-assets/skills/tanstack-query-generator/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: tanstack-query-generator
+description: Design of the ejected Redocly `tanstack-query` client generator. Read it, and update it, before changing generators/tanstack-query/.
+---
+
+# The `tanstack-query` generator — its skill
+
+This file is the DESIGN of your ejected `tanstack-query` generator (`generators/tanstack-query/`):
+**to change the generator, edit this skill first, then make the code match it** — a diff
+to `generators/tanstack-query/` that has no covering sentence here is incomplete.
+
+## What it emits
+
+Query/mutation option factories for TanStack Query — `<op>Options()`,
+`<op>Mutation()`, and `<op>InfiniteOptions()` for paginated operations — plus exported
+query keys. One generator, four framework variants (`react` default, `-vue`,
+`-svelte`, `-solid`) differing only in the imported package.
+
+## Design decisions that must hold
+
+- **Options factories, not hooks:** consumers call `useQuery(<op>Options(...))`, so the
+  output works with any of the framework adapters and stays testable.
+- **`queryKeyPrefix`** namespaces every key when several clients share a cache.
+- **Infinite queries** derive `getNextPageParam` from the resolved pagination rule; a
+  `link`-style rule reads the `Link` header the descriptor declares.
+- **`envelope` is excluded and stripped** — cached data is the plain body.
+- Requires `typescript`; throw-mode only (it wraps thrown errors into query errors).
+
+## The stage files
+
+`render.ts` holds the whole factory renderer; `index.ts` is the entry (the framework is
+its one argument). The wrappable-operation policy and the sdk calling convention come
+from the typescript generator's published contract
+(`@redocly/client-generator/contracts/typescript`); the resolved pagination arrives from
+the pipeline on the generator input.
+
+## Ejecting it
+
+`redocly eject-generator tanstack-query` copies this generator's TypeScript source folder
+to `generators/tanstack-query/`, exactly as we wrote it, importing
+`@redocly/client-generator`, `@redocly/client-generator/printers/typescript`, and
+`@redocly/client-generator/contracts/typescript`. Running a `.ts` generator uses Node's
+type stripping (Node 22.18, 23.6, or newer); newer built-in versions merge in per file
+with `--update`. The framework is a single argument in the ejected `index.ts` default
+export (`tanstackQueryGenerator('react')`), so switch it to `'vue'`, `'svelte'`, or
+`'solid'` there instead of ejecting four near-identical copies.
+
+## The modify loop
+
+1. Edit this skill: state the new behavior or decision.
+2. Make `generators/tanstack-query/` match it.
+3. Run `redocly generate-client` and inspect the `git diff` of the generated output —
+   generated files are never hand-edited.
+
+Newer built-in versions merge in with `redocly eject-generator tanstack-query --update`.