feat(client-generator): agent-friendly generators — python, go, php, cli + neutral authoring toolkit and eject workflow

.changeset/agent-friendly-generators.md

@@ -0,0 +1,6 @@
+---
+'@redocly/client-generator': minor
+'@redocly/cli': minor
+---
+
+Added agent-friendly client generation: `python`, `go`, `php`, and `cli` generators beside the TypeScript client, each self-documenting with `--docs`, configurable per generator, and available as source in your own repository through `eject-generator`.

.claude/rules/architecture.md

@@ -0,0 +1,47 @@
+# Repository architecture
+
+Where things live, so a change lands in the right package.
+
+This is a TypeScript monorepo with npm workspaces containing four packages:
+
+## `packages/core` (@redocly/openapi-core)
+
+The heart of the project.
+Handles all OpenAPI/AsyncAPI linting, validation, bundling, and decoration logic.
+This package is also used in external apps such as `language-server` and `vs-code-extension`.
+
+Key directories:
+
+- `src/rules/` — Built-in linting rules, organized by spec type (`oas2/`, `oas3/`, `oas3_1/`, `async2/`, `async3/`, `arazzo/`, `common/`). Each rule is its own file.
+- `src/config/` — Configuration loading and resolution (reads `redocly.yaml`).
+- `src/decorators/` — Built-in decorators for transforming API descriptions.
+- `src/bundle/` — Bundling logic that resolves `$ref` across multiple files.
+- `src/resolve.ts` — Document resolution for multi-file specs (local and remote).
+- `src/types/` — TypeScript type definitions for OAS2, OAS3, AsyncAPI, Arazzo.
+
+## `packages/cli` (@redocly/cli)
+
+User-facing CLI layer built on top of core.
+Uses yargs for argument parsing.
+
+- `src/index.ts` — Main command dispatcher.
+- `src/commands/` — One file per command.
+- Commands use `commandWrapper()` for consistent output, config loading, config linting, and exit codes (0 = success, 1 = execution error, 2 = config error).
+
+## `packages/respect-core` (@redocly/respect-core)
+
+API contract testing framework.
+Validates real API responses against OpenAPI/Arazzo specs.
+
+- `src/run.ts` — Test execution logic.
+- `src/modules/` — Core testing modules, including runtime expression evaluation.
+
+## `packages/client-generator` (@redocly/client-generator)
+
+Experimental package for generating clients from OpenAPI descriptions — the TypeScript client
+plus the `python`, `go`, and `php` SDKs, the generated CLI, and its Markdown reference.
+
+- `src/intermediate-representation/` — the language-neutral API model every generator reads.
+- `src/emitters/` — the renderers that turn that model into source text.
+- `src/generators/` — one folder per generator: a thin entry plus the design skill it must match.
+- `src/authoring/` — the language-neutral toolkit generators are written with, ours and users'.

.claude/rules/core-principles.md

@@ -19,7 +19,7 @@ Release and commit mechanics are procedures, not principles — they live in
 
 1. Respect the core patterns: Walker, Visitors, and Nodes.
    New rules and decorators follow this pattern instead of using regex or manual drilling objects described by the supported specifications.
-   The full guide is in [`rules-system.md`](./rules-system.md).
+   The full guide is in [the `rules-system` skill](../skills/rules-system/SKILL.md).
 
 1. Explain in chat, not in files.
    Don't create explanation, summary, or design files unless asked.

.claude/rules/testing.md

@@ -2,10 +2,52 @@
 
 1. Write meaningful tests that exercise real behavior — not tests that exist only to raise coverage.
    One focused, clear test is enough.
-1. Rule tests are unit tests by convention: parse a YAML document, run `lintDocument`, and assert with `toMatchInlineSnapshot` — a behavior test in itself (given this input, these problems).
+1. A unit test lives in a `__tests__` folder beside the file it tests, and mirrors its name:
+   `src/commands/eject-generator.ts` is tested by `src/commands/__tests__/eject-generator.test.ts`.
+   Do not rebuild the source tree inside a `__tests__` folder (`src/__tests__/commands/…`) — the
+   older tests that do are historical, and a reviewer should not have to guess which layout a
+   new test follows. One module gets one test file: split a long one by `describe`, not by adding
+   a second file for the same source.
+1. Rule tests are unit tests by convention: parse a YAML document, run `lintDocument`, and assert
+   with `toMatchInlineSnapshot` — a behavior test in itself (given this input, these problems).
    Generate new snapshots and update stale ones as part of the change.
+
+   The pattern — parse, lint, assert on the whole output:
+
+   ```ts
+   import { outdent } from 'outdent';
+   import { parseYamlToDocument, replaceSourceWithRef } from '../../../../__tests__/utils.js';
+   import { createConfig } from '../../../config/index.js';
+   import { lintDocument } from '../../../lint.js';
+   import { BaseResolver } from '../../../resolve.js';
+
+   describe('Oas3 no-my-rule', () => {
+     it('should report a violation', async () => {
+       const document = parseYamlToDocument(
+         outdent`
+           openapi: 3.0.0
+           ...
+         `,
+         'foobar.yaml'
+       );
+
+       const results = await lintDocument({
+         externalRefResolver: new BaseResolver(),
+         document,
+         config: await createConfig({ rules: { 'no-my-rule': 'error' } }),
+       });
+
+       expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`...`);
+     });
+   });
+   ```
+
 1. Compile before testing.
+
    Unit tests import from `lib/` (compiled output), not `src/` — run `npm run compile` after every change.
+
 1. Run the full suite (`npm test`) when you touch core linting logic, and make sure all tests pass in CI.
+1. Client generation has its own suite: `npm run client-generators` runs the client-generator unit tests plus the `tests/e2e/generate-client` bars (which compile real Python/Go/PHP/TypeScript output).
+   Run it for any generation change; `npm run e2e` does not include those tests.
 1. Coverage thresholds (`vitest.config.ts`) are a guide, not a number to game.
    If a feature or fix is already covered by e2e tests, propose lowering the threshold rather than padding the suite with unit tests that only chase coverage.

.claude/skills/redocly-cli/SKILL.md

@@ -126,7 +126,7 @@ Configure it durably under a `client` block in `redocly.yaml` instead of flags:
 
 ```yaml
 client:
-  generators: [sdk, zod] # add-ons: tanstack-query, swr, mock, transformers, or a plugin path
+  generators: [typescript, zod] # add-ons: tanstack-query, swr, mock, transformers, or a plugin path
   outputMode: split
   pagination: # config-only, no CLI flag
     style: cursor

.claude/rules/rules-system.md → .claude/skills/rules-system/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: rules-system
+description: How to write built-in lint rules and decorators for packages/core — the Walker/Visitors/Nodes pattern, visitor hooks, the ctx object, rule registration, and stateful rule examples. Use when adding or changing a rule, decorator, or preprocessor.
+---
+
 ## Rules System: Walker, Visitors, and Nodes
 
 This is the most important pattern to understand when working in `packages/core`.

.github/workflows/tests.yaml

@@ -37,10 +37,24 @@ jobs:
         uses: davelosert/vitest-coverage-report-action@d63aa97db4c0319f304f1787689de1ca548365cf # v2.11.1
 
   e2e:
-    # The e2e suite is split across shards so no single runner carries the whole set.
-    # Running all suites in one step was cancelled mid-run by the Actions service once the
-    # generate-client suites grew past ~28 (a healthy runner, no resource exhaustion);
-    # each shard stays well under that.
+    # Everything under tests/e2e EXCEPT generate-client, which has its own job below.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 24
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: E2E Tests
+        run: npm run e2e
+
+  client-generators:
+    # Client generation has its own job: the client-generator unit tests plus the
+    # generate-client e2e bars, which compile real Python, Go, PHP, and TypeScript output
+    # (including big real-world descriptions) — the slowest tests we have, needing
+    # toolchains nothing else does. Adding a language bar here cannot slow the shared e2e job.
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -52,10 +66,22 @@ jobs:
         with:
           node-version: 24
           cache: npm
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.12'
+      - name: Install httpx and pydantic (the Python import bars need them)
+        run: pip install httpx pydantic
+      # Go, gofmt, and php come with the runner image; a bar whose toolchain is missing
+      # skips itself, so a thinner image degrades coverage instead of failing the job.
+      - name: Cache the pinned GitHub REST description
+        uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+        with:
+          path: tests/e2e/generate-client/.cache
+          key: large-descriptions-${{ hashFiles('tests/e2e/generate-client/large-descriptions.test.ts') }}
       - name: Install dependencies
         run: npm ci
-      - name: E2E Tests (shard ${{ matrix.shard }}/2)
-        run: npm run e2e -- --shard=${{ matrix.shard }}/2
+      - name: Client generator tests (shard ${{ matrix.shard }}/2)
+        run: npm run client-generators -- --shard=${{ matrix.shard }}/2
 
   examples:
     # The examples gitignore their generated clients (only zero-install-quickstart commits

.gitignore

@@ -25,4 +25,5 @@ __changesets__.json
 **/.claude/agent-registry.json
 **/.claude/agent-memory-local
 **/.claude/first-run
-**/.claude/assistant-daemon-state.json
+**/.claude/assistant-daemon-state.json
+__pycache__/

.oxfmtrc.json

@@ -11,6 +11,7 @@
     "packages/core/src/rules/common/__tests__/fixtures/invalid-yaml.yaml",
     "tests/performance/api-definitions/",
     "tests/e2e/generate-client/examples/*/src/api/",
+    "tests/e2e/generate-client/examples/*/generators/",
     "tests/e2e/generate-client/*-consumer/api*.ts",
     "tests/smoke/**/*.yaml",
     "snapshot*.txt",

AGENTS.md

@@ -46,9 +46,12 @@ npm run unit -- -t 'test name pattern'
 # Update snapshots
 npm run unit -- -u
 
-# Run e2e tests
+# Run e2e tests (everything under tests/e2e except generate-client)
 npm run e2e
 
+# Run every generator test (client-generator unit + generate-client e2e)
+npm run client-generators
+
 # Run the full test suite (compile + typecheck + unit + e2e)
 npm test
 
@@ -64,47 +67,13 @@ npm run cli -- lint openapi.yaml
 
 ## Architecture
 
-This is a TypeScript monorepo with npm workspaces containing four packages:
-
-### `packages/core` (@redocly/openapi-core)
-
-The heart of the project.
-Handles all OpenAPI/AsyncAPI linting, validation, bundling, and decoration logic.
-This package is also used in external apps such as `language-server` and `vs-code-extension`.
-
-Key directories:
-
-- `src/rules/` — Built-in linting rules, organized by spec type (`oas2/`, `oas3/`, `oas3_1/`, `async2/`, `async3/`, `arazzo/`, `common/`). Each rule is its own file.
-- `src/config/` — Configuration loading and resolution (reads `redocly.yaml`).
-- `src/decorators/` — Built-in decorators for transforming API descriptions.
-- `src/bundle/` — Bundling logic that resolves `$ref` across multiple files.
-- `src/resolve.ts` — Document resolution for multi-file specs (local and remote).
-- `src/types/` — TypeScript type definitions for OAS2, OAS3, AsyncAPI, Arazzo.
-
-### `packages/cli` (@redocly/cli)
-
-User-facing CLI layer built on top of core.
-Uses yargs for argument parsing.
-
-- `src/index.ts` — Main command dispatcher.
-- `src/commands/` — One file per command.
-- Commands use `commandWrapper()` for consistent output, config loading, config linting, and exit codes (0 = success, 1 = execution error, 2 = config error).
-
-### `packages/respect-core` (@redocly/respect-core)
-
-API contract testing framework.
-Validates real API responses against OpenAPI/Arazzo specs.
-
-- `src/run.ts` — Test execution logic.
-- `src/modules/` — Core testing modules, including runtime expression evaluation.
-
-### `packages/client-generator` (@redocly/client-generator)
-
-Experimental package for generating TypeScript clients from OpenAPI specs.
+Where each package sits, and the key directories inside it, are in
+[`.claude/rules/architecture.md`](./.claude/rules/architecture.md) — read it before a change lands
+in the wrong package.
 
 ## Build System
 
-`packages/core`, `packages/respect-core`, and `packages/client-generator` are compiled by TypeScript (`tsc -b tsconfig.build.json`).
+`packages/core` and `packages/respect-core` are compiled by TypeScript (`tsc -b tsconfig.build.json`).
 `packages/cli` is bundled by esbuild (`packages/cli/scripts/build.mjs`) — it produces `lib/index.js` (entry chunk, ~450 kB) and lazy chunks under `lib/chunks/` (redoc + react, loaded only when `build-docs` runs).
 The root `npm run compile` runs both steps: tsc for core/respect-core, then the esbuild bundle for the CLI.
 
@@ -114,7 +83,7 @@ The published CLI package ships from a staged `.publish/` directory (created by
 
 Linting in `packages/core` rests on three concepts: the **Walker** traverses the parsed API description and resolves `$ref`s, **Visitors** are objects keyed by **Node** type, and the Walker calls each visitor's `enter` / `leave` / `skip` hooks as it reaches a node.
 New rules and decorators follow this pattern instead of parsing documents by hand.
-The full guide, with examples, is in [`.claude/rules/rules-system.md`](./.claude/rules/rules-system.md).
+The full guide, with examples, is in [the `rules-system` skill](./.claude/skills/rules-system/SKILL.md).
 
 ## Add or change a built-in rule
 
@@ -144,40 +113,11 @@ Naming and reuse:
 - A `redocly.yaml` in the repository root affects unit tests in the CLI package.
   Remove it before running them.
 - Run the full suite (`npm test`) when you touch core linting logic.
+- Run `npm run client-generators` when you touch client generation — it is the whole generator suite in one command.
 
-The full testing and QA rules are in
+The full testing and QA rules — including the rule test pattern to copy — are in
 [`.claude/rules/testing.md`](./.claude/rules/testing.md).
 
-The rule test pattern looks like this:
-
-```ts
-import { outdent } from 'outdent';
-import { parseYamlToDocument, replaceSourceWithRef } from '../../../../__tests__/utils.js';
-import { createConfig } from '../../../config/index.js';
-import { lintDocument } from '../../../lint.js';
-import { BaseResolver } from '../../../resolve.js';
-
-describe('Oas3 no-my-rule', () => {
-  it('should report a violation', async () => {
-    const document = parseYamlToDocument(
-      outdent`
-        openapi: 3.0.0
-        ...
-      `,
-      'foobar.yaml'
-    );
-
-    const results = await lintDocument({
-      externalRefResolver: new BaseResolver(),
-      document,
-      config: await createConfig({ rules: { 'no-my-rule': 'error' } }),
-    });
-
-    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`...`);
-  });
-});
-```
-
 ## Code quality — no AI slop
 
 Before opening a PR, strip the things an assistant tends to add that a human reviewer would not:
@@ -207,7 +147,7 @@ The full release and commit workflow is in [`.claude/rules/workflow.md`](./.clau
 
 - Every feature or fix needs a changeset: run `npx changeset` and describe the change in sentence case.
   If the change lives in `packages/core` or `packages/respect-core` but affects CLI behavior, include `@redocly/cli` as well.
-  `@redocly/cli`, `@redocly/openapi-core`, and `@redocly/respect-core` share one version and release together; `@redocly/client-generator` is versioned separately.
+  All three packages share one version and release together.
 - Use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages.
 - Don't add AI co-author or "Generated by" lines to commits.
 - Don't modify the pull request template.

CONTRIBUTING.md

@@ -238,6 +238,28 @@ Note that the snapshot does not always match the command output because of the w
 This is intentional so outputs stay consistent for snapshot testing.
 The order of stdout and stderr in a snapshot may differ from what you see in the terminal, but the combined output is stable.
 
+### Generator tests
+
+Client generation has its own suite: `npm run client-generators` runs the `@redocly/client-generator` unit tests together with the `tests/e2e/generate-client` end-to-end tests, so one command covers everything about generation.
+
+```bash
+npm run client-generators                                   # every generator test
+npm run client-generators -- tests/e2e/generate-client/go.test.ts   # one file
+npm run client-generators -- -t 'gofmt'                     # by test name
+```
+
+Those e2e tests compile their output with real toolchains, so what is available decides what runs:
+
+- **Python** (`python3`, plus `httpx` for the import bars) and **Go** (`go build`, `go vet`, `gofmt`) and **PHP** (`php -l`) — a bar for a missing toolchain skips itself rather than failing, so a partial local setup still gives a useful run. CI installs Python and `httpx`; Go and PHP come with the runner image.
+- The largest bars generate from big real-world descriptions (Rebilly, the GitHub REST API), which is why they are slow and why the suite has its own CI job — a growing set of compiled-language bars must not slow the shared e2e job.
+
+`npm run e2e` covers everything under `tests/e2e/` **except** `generate-client`.
+`npm run unit` still includes the client-generator unit tests, so the coverage report stays whole.
+
+Several of these tests run a local HTTP server and assert on its request log.
+On a machine with many cores, vitest runs enough of them in parallel to occasionally reset a connection — a failure that says nothing about the code under test.
+Reading a server's log goes through `serverLog()` in `tests/e2e/generate-client/helpers.ts`, which retries for that reason; if you see an isolated `ECONNRESET` or `fetch failed`, re-run the file before investigating.
+
 ### Smoke tests
 
 Smokes are for testing the CLI in different environments.