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`, `cli`, and `cli-docs` generators beside the TypeScript ones, a language-neutral authoring toolkit with per-generator options, and an `eject-generator` command that vendors any built-in generator — plus its design as an agent skill — into your repo.

.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

@@ -7,5 +7,7 @@
 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 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` no longer includes 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.

.github/workflows/tests.yaml

@@ -37,10 +37,31 @@ 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.
+    # 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 suite count grew past
+    # ~28 (a healthy runner, no resource exhaustion), and each shard stays well under that.
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3]
+    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 (shard ${{ matrix.shard }}/3)
+        run: npm run e2e -- --shard=${{ matrix.shard }}/3
+
+  generators:
+    # Client generation has its own job: its bars compile real Python, Go, PHP, and
+    # TypeScript output from generated clients (including big real-world descriptions), so
+    # they are the slowest tests we have and they need toolchains nothing else does.
+    # Keeping them here means adding another language bar cannot slow the shared e2e job.
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -52,10 +73,22 @@ jobs:
         with:
           node-version: 24
           cache: npm
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.12'
+      - name: Install httpx (the Python import bars need it)
+        run: pip install httpx
+      # 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: Generator Tests (shard ${{ matrix.shard }}/2)
+        run: npm run generators -- --shard=${{ matrix.shard }}/2
 
   examples:
     # The examples gitignore their generated clients (only zero-install-quickstart commits

.gitignore

@@ -25,4 +25,6 @@ __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",