openapi-client-codegen 0.1.5__tar.gz → 0.1.7__tar.gz

openapi_client_codegen-0.1.7/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Preflight
+        run: uvx --from python-devkit==0.1.5 preflight-python
+
+  publish:
+    needs: check
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+
+      # Workaround: fetch-tags is broken with shallow clones
+      - run: git fetch --tags origin
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Publish
+        run: uvx --from release-devkit==0.1.3 publish-packages --config publish-config.json

{openapi_client_codegen-0.1.5 → openapi_client_codegen-0.1.7}/AGENTS.md

@@ -2,30 +2,30 @@
 
 ## What this is
 
-`openapi-client-codegen` wraps [OpenAPI Generator](https://openapi-generator.tech/) to turn an OpenAPI schema into typed client packages — a Python (`httpx`) client and a Unity-consumable C# (`httpclient`) client. It owns every step that is generic across consumers: the project orchestration loop, downgrading 3.1→3.0, the committed-spec unchanged skip, authoring and patching the C# templates, running the generator, and writing the Unity package metadata. The caller owns what is inherently project-specific: **producing the OpenAPI spec** (injected as a required strategy — any callable from project directory to raw spec JSON; the org's uv convention ships as `dump_openapi_spec`), the project→client mapping, the naming root, the npm scope, license, repository URL, and the generated output root.
+`openapi-client-codegen` wraps [OpenAPI Generator](https://openapi-generator.tech/) to turn an OpenAPI schema into typed client packages — a Python (`httpx`) client and a Unity-consumable C# (`httpclient`) client. It owns every step that is generic across consumers: the project orchestration loop, downgrading 3.1→3.0, the committed-spec unchanged skip, authoring and patching the C# templates, running the generator, and writing the Unity package metadata. The caller owns what is inherently project-specific: **producing the OpenAPI spec** (a command string in the consumer's config, run by the library's `SpecProducer`), the project→client mapping, the naming root, the npm scope, license, repository URL, and the generated output root — all as fields of the `ProjectsConfig` model.
 
-The package is `openapi_client_codegen` (src-layout under `src/openapi_client_codegen/`), renamed from `openapi-clientgen` before the first publish (operator, 2026-09-20 — no artifact carries the old name). Its Python dependencies are `bashrun` (the guardrailed subprocess wrapper) and `typer` (the thin CLI), both from PyPI — git-source pins only in scratch branches testing unreleased changes. At **runtime** it also needs **Java (JDK 11+)** and **`uvx`** on PATH — the generator itself runs as `uvx --from 'openapi-generator-cli[jdk4py]==<pin>' ...`.
+The package is `openapi_client_codegen` (src-layout under `src/openapi_client_codegen/`), renamed from `openapi-clientgen` before the first publish (operator, 2026-09-20 — no artifact carries the old name). Its Python dependencies are `bashrun` (the guardrailed subprocess wrapper), `pydantic` (the config schema), and `typer` (the thin CLI), all from PyPI — git-source pins only in scratch branches testing unreleased changes. At **runtime** it also needs **Java (JDK 11+)** and **`uvx`** on PATH — the generator itself runs as `uvx --from 'openapi-generator-cli[jdk4py]==<pin>' ...`.
 
 ## Release flow
 
-Publishing rides `ci.yml`'s `publish` job on every push to `main` (gated on the check job): release-devkit's publish composite action (pinned by SHA; the uvx invocation runs inside the caller's job, keeping OIDC identity local), never a project dependency (openapi-client-codegen sits inside release-devkit's transitive dependency graph; a project-level edge is a resolver cycle) — computes the plan from the tag ledger and path-diff, patches the version ephemerally, and publishes to PyPI under OIDC trusted publishing (pending publisher bound to `ci.yml`, no environment). The committed `pyproject.toml` version is permanently the `0.0.0.dev0` sentinel; the `openapi-client-codegen-v*` tags are the version ledger (first release `0.1.0`, patch-auto thereafter). API-breaking changes ship with a manually bumped version — patch-auto assumes additive changes.
+Publishing rides `ci.yml`'s `publish` job on every push to `main` (gated on the check job): release-devkit's `publish-packages` (an inlined, version-pinned `uvx` step in the publish job, keeping OIDC identity local), never a project dependency (openapi-client-codegen sits inside release-devkit's transitive dependency graph; a project-level edge is a resolver cycle) — computes the plan from the tag ledger and path-diff, patches the version ephemerally, and publishes to PyPI under OIDC trusted publishing (pending publisher bound to `ci.yml`, no environment). The committed `pyproject.toml` version is permanently the `0.0.0.dev0` sentinel; the `openapi-client-codegen-v*` tags are the version ledger (first release `0.1.0`, patch-auto thereafter). API-breaking changes ship with a manually bumped version — patch-auto assumes additive changes.
 
 ## Public API
 
-The package init is empty (RUF067 strict mode — the canonical ruff config bans any content in `__init__.py`); import each symbol from its defining module: `client` (`generate_client`), `downgrade` (`downgrade_openapi_3_1_to_3_0`, `JsonDict`), `naming` (`ClientNaming`, `DefaultNamingPolicy`, `NamingPolicy`), `orchestrator` (`generate_projects`, `dump_openapi_spec`, `SpecProducer`), `templates` (`regenerate_templates`), `unity` (`write_unity_package_metadata`).
+The package init is empty (RUF067 strict mode — the canonical ruff config bans any content in `__init__.py`); import each symbol from its defining module: `client` (`generate_client`), `cli` (`app`), `downgrade` (`downgrade_openapi_3_1_to_3_0`, `JsonDict`), `orchestrator` (`ProjectsConfig`, `ClientNaming`, `SpecProducer`), `templates` (`regenerate_templates`), `unity` (`write_unity_package_metadata`).
 
 | Symbol | Role |
 |---|---|
 | `downgrade_openapi_3_1_to_3_0(schema)` | In-place 3.1.0→3.0.3 fixup (openapi-generator rejects 3.1). Pure function. |
-| `generate_projects(projects, root_name, generated_root, dump_spec, npm_scope=None, license_spdx=None, repository_url=None, project=None, client=None, no_cache=False, root=Path())` | The project orchestrator: per mapping entry (`{project path: [generators]}`), produce the spec via the injected `dump_spec` strategy, downgrade it, write `<project>/openapi.json` unless byte-identical to the committed spec (`no_cache` forces through), and `generate_client` per listed generator into `<generated_root>/<generator>/<names.base>`. `project` / `client` restrict the run to one entry; `root` is what project paths resolve against. |
-| `SpecProducer(command)` | Callable class wrapping any shell command that prints the spec to stdout, run with the project directory as cwd; the CLI `--spec-command` bridge. The strategy contract itself is untyped vocabulary — any `Callable[[Path], str]` (project directory in, raw OpenAPI JSON out) satisfies `dump_spec`. |
-| `dump_openapi_spec(project)` | The org strategy: `uv run --project . python -m src.dump_openapi` with `CODEGEN=1` gating heavy imports (per-call env overlay). Shipped as the exemplar — `dump_spec` is required, so every consumer names its strategy explicitly. |
+| `ProjectsConfig` | The pydantic schema of a consumer's client-generation config (`extra="forbid"`): required `projects`, `root_name`, `generated_root`, `spec_command`; optional `spec_env`, `npm_scope`, `license_spdx`, `repository_url`. The single source of identity — the CLI validates the `--config` file into it and consumes it; nothing overrides it per invocation. |
+| `SpecProducer(command, env=None)` | Callable class wrapping any command that prints the spec to stdout, run with the project directory as cwd and an optional per-call env overlay; the CLI command builds it from the config's `spec_command` / `spec_env`, and programmatic consumers construct it directly. |
+| `app` | The single-command CLI (invoked directly, no subcommand) behind the `openapi-client-codegen` console script and consumer `[project.scripts]` aliases (e.g. placeframe's `generate-clients`). It validates the `--config` JSON against the `ProjectsConfig` pydantic model (`extra="forbid"`: unknown keys rejected — a `ValidationError` propagates) and then runs the whole orchestration itself: per mapping entry (`projects` maps project paths to generator lists), produce the spec via `SpecProducer`, downgrade it, write `<project>/openapi.json` unless byte-identical to the committed spec (`no_cache` forces through), and `generate_client` per listed generator into `<generated_root>/<generator>/<names.base>`. The flags are invocation-scoped only (filters, `--no-cache`, `--root`; project paths resolve against `root`). Commands run shell-less (shlex-split, operators rejected), so env gating is the structured `spec_env`, never a `VAR=…` prefix. |
 | `regenerate_templates(target_dir, extra_patches_dir=None)` | Author the C# templates into `target_dir/csharp` and apply the shipped (then optional extra) patches. |
 | `generate_client(spec, generator, output_dir, names, templates_dir=None, extra_references=None, npm_scope=None, license_spdx=None, repository_url=None)` | Run the generator for one `(spec, generator)` and sync the result into `output_dir`. `templates_dir` is required for `csharp`. For csharp, `npm_scope` composes the UPM identity `{scope}.{base-minus-dashes}` (e.g. `org.outernet.placeframe.apiclient`); unset falls back to the legacy `org.nuget.{camel-lower}` identity. `license_spdx` / `repository_url` populate the manifest's `license` / `repository` fields when given. |
 | `write_unity_package_metadata(package_dir, package_name, extra_references=None, npm_name=None, license_spdx=None, repository_url=None)` | Write `package.json` / `.asmdef` / `csc.rsp` / `Directory.Build.props`. Called by `generate_client` for csharp. |
-| `DefaultNamingPolicy(root_name)` / `ClientNaming` / `NamingPolicy` | Package-name derivation. `DefaultNamingPolicy("placeframe")("docker/api")` → base `api-client`, dashed `placeframe-api-client`, underscored `placeframe_api_client`, camel `PlaceframeApiClient`. |
+| `ClientNaming` | The derived per-project package identity: `base` (last path segment + `-client`), `dashed` (`{root_name}-{base}`), `underscored`, `camel`. Constructed inline by the CLI command per project; `DefaultNamingPolicy("placeframe")("docker/api")` semantics live there. |
 
-`generate_projects` orchestrates the whole run — `regenerate_templates` once, then per project: produce (via the injected strategy) → downgrade → committed-spec skip → per-client generate. Consumers hand it their parsed mapping, their spec-production strategy, and their identity parameters. The generator version pin and the shipped configs/patches/ignore-file live in `src/openapi_client_codegen/_data/` (paths in `_data.py`).
+The CLI command orchestrates the whole run — `regenerate_templates` once, then per project: produce (via the config-built `SpecProducer`) → downgrade → committed-spec skip → per-client generate. The generator version pin and the shipped configs/patches/ignore-file live in `src/openapi_client_codegen/_data/` (paths in `_data.py`).
 
 ## Constraints
 
@@ -37,7 +37,7 @@ To author a new patch: author the raw templates (`openapi-generator-cli author t
 
 ### Generator env vars are passed per-call, never set at module level
 
-`JAVA_OPTS=-Dlog.level=warn` (quiets the generator) is passed as `bash(..., env={"JAVA_OPTS": "-Dlog.level=warn"})` on the two `openapi-generator-cli` calls that need it, so it reaches only those child processes and never touches this process's `os.environ`. `bashrun`'s `env=` overlays the inherited environment for that one child (see its AGENTS.md), which is the whole point — the alternative, mutating the global `os.environ`, leaks the var into every later subprocess. This covers only the generator this package runs itself. The shipped `dump_openapi_spec` strategy follows the same rule: `CODEGEN=1` (which gates a service's heavy imports so the app imports cleanly for the dump) rides bashrun's per-call env overlay and never touches this process's `os.environ`.
+`JAVA_OPTS=-Dlog.level=warn` (quiets the generator) is passed as `bash(..., env={"JAVA_OPTS": "-Dlog.level=warn"})` on the two `openapi-generator-cli` calls that need it, so it reaches only those child processes and never touches this process's `os.environ`. `bashrun`'s `env=` overlays the inherited environment for that one child (see its AGENTS.md), which is the whole point — the alternative, mutating the global `os.environ`, leaks the var into every later subprocess. This covers the generator this package runs itself; a consumer's spec command needing the same gating (e.g. `CODEGEN=1`) carries it in the config's structured `spec_env` key, which rides the same per-call overlay.
 
 ### The Unity reference set is coupled to the patched templates
 
@@ -51,7 +51,7 @@ The generated `.csproj` stays inside the UPM package because it is the `dotnet p
 
 ### What the consumer owns
 
-The spec-production strategy (`dump_spec`, required — the package is consumable by projects that use no Python, no uv, or no dump entry point at all; the org's `dump_openapi_spec` ships beside it, and a project whose spec is a committed file needs only a file read), the project→clients mapping (in whatever config shape it likes — the verb takes the parsed mapping, not a file path), the naming root, the npm scope, license, repository URL, and the generated output root. The orchestrator iterates the mapping itself and fixes `DefaultNamingPolicy`; a consumer needing a different policy calls the per-client API directly — `NamingPolicy` is a `Protocol`, any callable `(project: str) -> ClientNaming` works there.
+The spec-production command (`spec_command` + optional `spec_env`, required — the package is consumable by projects that use no Python, no uv, or no dump entry point at all; a project whose spec is a committed file needs only `cat openapi.json`), the project→clients mapping, the naming root, the npm scope, license, repository URL, and the generated output root — all fields of the `ProjectsConfig` model, all carried in the consumer's config file, none overridable per invocation. Naming derivation is fixed inside the CLI command (`ClientNaming` built inline per project from the root name and the project's last path segment); a consumer needing different names calls the per-client API directly with its own `ClientNaming`.
 
 ## See also
 

{openapi_client_codegen-0.1.5 → openapi_client_codegen-0.1.7}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.5
 Name: openapi-client-codegen
-Version: 0.1.5
+Version: 0.1.7
 Summary: OpenAPI client-generation wrapper: Litestar spec dump, 3.1->3.0 downgrade, patched openapi-generator templates, Unity package metadata
 License-File: LICENSE
 License-File: NOTICE
 Requires-Python: >=3.13
 Requires-Dist: bashrun>=0.1.0
+Requires-Dist: pydantic>=2.11.7
 Requires-Dist: typer>=0.17.4

openapi_client_codegen-0.1.7/README.md

@@ -0,0 +1,70 @@
+# openapi-client-codegen
+
+Generate typed API clients from an OpenAPI schema. `openapi-client-codegen` wraps [OpenAPI Generator](https://openapi-generator.tech/): it downgrades OpenAPI 3.1→3.0 (the generator only accepts 3.0), authors and patches the C# templates, runs the generator, and writes Unity package metadata. It produces a Python (`httpx`) client and a Unity-consumable C# (`httpclient`) client.
+
+The generic steps live here; the caller supplies the spec-production strategy (any callable from project directory to raw spec JSON — a shell command carried in the CLI config), the project→client mapping, the naming root, the npm scope, license, repository URL, and the output root. See [`AGENTS.md`](./AGENTS.md) for the API surface, the lib-owns/consumer-owns boundary, and the patch mechanism.
+
+## Requirements
+
+- Python 3.13+ and [uv](https://docs.astral.sh/uv/)
+- **Java (JDK 11+)** and **`uvx`** on PATH at runtime — the generator runs as `uvx --from 'openapi-generator-cli[jdk4py]==<pin>' ...`
+
+## CLI
+
+The CLI is the multi-project orchestrator, invoked directly (single command, no subcommand):
+
+```bash
+uv run openapi-client-codegen --config clients.json
+```
+
+`clients.json` carries everything consumer-owned in one place:
+
+```json
+{
+  "projects": {"services/api": ["python", "csharp"]},
+  "root_name": "myproject",
+  "generated_root": "generated",
+  "spec_command": "uv run --project . python -m src.dump_openapi",
+  "spec_env": {"CODEGEN": "1"},
+  "npm_scope": "org.example.myproject",
+  "license_spdx": "Apache-2.0",
+  "repository_url": "https://github.com/org/repo.git"
+}
+```
+
+`spec_command` is a command that prints the project's raw OpenAPI JSON to stdout, run with the project directory as cwd — no shell sits in front of it (commands are shlex-split; operators like `|` are rejected), so env gating rides the structured `spec_env` key, overlaid per call. The config is the single source of identity: `root_name`, `generated_root`, and `spec_command` are required there, and nothing overrides them per invocation — a different identity is a different config file. The remaining flags are invocation-scoped (`--project` / `--client` filters, `--no-cache`, `--root`). The orchestrator downgrades each produced spec, skips generation when the committed `<project>/openapi.json` is byte-identical (`--no-cache` forces through), and syncs each client under `<generated-root>/<generator>/<base-name>`.
+
+To run it as a first-class command in a consumer repo, point a `[project.scripts]` entry at the same app — e.g. `generate-clients = "openapi_client_codegen.cli:app"`.
+
+The same config drives the library API, for in-process consumption from a consumer's own command:
+
+```python
+from pathlib import Path
+
+from openapi_client_codegen.orchestrator import ProjectsConfig, generate_projects
+
+config = ProjectsConfig.model_validate_json(Path("clients.json").read_text(encoding="utf-8"))
+generate_projects(config)
+```
+
+A non-uv project declares its own `spec_command` instead — e.g. `dotnet run -- dump-openapi`; a project whose spec is a committed file uses `cat openapi.json`.
+
+## Consuming from another repo
+
+Install from PyPI:
+
+```toml
+[project]
+dependencies = ["openapi-client-codegen>=0.1.0"]
+```
+
+`bashrun` resolves transitively. At **runtime** the generator also needs Java (JDK 11+) and `uvx` on PATH. To test an unreleased change, pin the repo at a git ref in a scratch branch instead (`openapi-client-codegen = { git = "…", rev = "<sha>" }` under `[tool.uv.sources]`) and drop the pin when the release lands.
+
+## Development
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+uv run pytest
+```

{openapi_client_codegen-0.1.5 → openapi_client_codegen-0.1.7}/pyproject.toml

@@ -1,10 +1,11 @@
 [project]
 name = "openapi-client-codegen"
-version = "0.1.5"
+version = "0.1.7"
 description = "OpenAPI client-generation wrapper: Litestar spec dump, 3.1->3.0 downgrade, patched openapi-generator templates, Unity package metadata"
 requires-python = ">=3.13"
 dependencies = [
     "bashrun>=0.1.0",
+    "pydantic>=2.11.7",
     "typer>=0.17.4",
 ]
 

openapi_client_codegen-0.1.7/src/openapi_client_codegen/cli.py

@@ -0,0 +1,80 @@
+import json
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import Annotated
+
+from typer import Option, Typer
+
+from .client import generate_client
+from .downgrade import downgrade_openapi_3_1_to_3_0
+from .orchestrator import ClientNaming, ProjectsConfig, SpecProducer
+from .templates import regenerate_templates
+
+app = Typer(pretty_exceptions_show_locals=False)
+
+
+@app.command()
+def generate_projects_command(
+    config: Annotated[
+        Path, Option(help="JSON config carrying the projects mapping, the client identity, and the spec command")
+    ],
+    project: Annotated[str | None, Option(help="Generate only this project, as keyed in the config")] = None,
+    client: Annotated[str | None, Option(help="Generate only this client generator")] = None,
+    no_cache: Annotated[
+        bool, Option("--no-cache", help="Regenerate even when the committed spec is unchanged")
+    ] = False,
+    root: Annotated[Path, Option(help="Repository root the project paths resolve against")] = Path(),
+) -> None:
+    settings = ProjectsConfig.model_validate_json(config.read_text(encoding="utf-8"))
+    root = root.resolve()
+    dump_spec = SpecProducer(settings.spec_command, env=settings.spec_env)
+
+    with TemporaryDirectory() as templates_directory_string:
+        templates_directory = Path(templates_directory_string)
+        regenerate_templates(templates_directory)
+
+        for project_name, clients in settings.projects.items():
+            if project is not None and project != project_name:
+                continue
+
+            project_directory = root / project_name
+            print(f"Producing OpenAPI spec for project: {project_directory}")
+
+            openapi_json = json.loads(dump_spec(project_directory))
+            downgrade_openapi_3_1_to_3_0(openapi_json)
+            openapi_spec = json.dumps(openapi_json, indent=2)
+
+            spec_path = project_directory / "openapi.json"
+
+            if spec_path.exists():
+                old_spec = spec_path.read_text(encoding="utf-8")
+
+                if openapi_spec == old_spec and not no_cache:
+                    print("OpenAPI spec unchanged, skipping client generation")
+                    continue
+
+            spec_path.write_text(openapi_spec, encoding="utf-8")
+
+            base = f"{project_name.rsplit('/', maxsplit=1)[-1]}-client"
+            dashed = f"{settings.root_name}-{base}"
+            names = ClientNaming(
+                base=base,
+                dashed=dashed,
+                underscored=dashed.replace("-", "_"),
+                camel=f"{settings.root_name.capitalize()}{''.join(part.capitalize() for part in base.split('-'))}",
+            )
+
+            for client_name in clients:
+                if client is not None and client_name != client:
+                    continue
+
+                generate_client(
+                    openapi_spec,
+                    client_name,
+                    settings.generated_root / client_name / names.base,
+                    names,
+                    templates_dir=templates_directory,
+                    npm_scope=settings.npm_scope,
+                    license_spdx=settings.license_spdx,
+                    repository_url=settings.repository_url,
+                )

{openapi_client_codegen-0.1.5 → openapi_client_codegen-0.1.7}/src/openapi_client_codegen/client.py

@@ -1,15 +1,21 @@
+from __future__ import annotations
+
 import json
+import sys
 from os import walk
 from pathlib import Path
 from shutil import copytree
 from tempfile import NamedTemporaryFile, TemporaryDirectory
+from typing import TYPE_CHECKING
 
 from bashrun.bash import bash
 
 from .resources import CONFIGS_DIR, IGNORE_FILE, OPENAPI_GENERATOR_CLI_VERSION
-from .naming import ClientNaming
 from .unity import write_unity_package_metadata
 
+if TYPE_CHECKING:
+    from .orchestrator import ClientNaming
+
 _HTTP_METHODS = ("get", "put", "post", "delete", "patch", "options", "head", "trace")
 
 
@@ -112,4 +118,4 @@ def generate_client(
         copytree(temporary_directory, output_dir, dirs_exist_ok=True)
 
     if generator == "python":
-        bash(f"uv pip install {output_dir.resolve().as_posix()}")
+        bash(f"uv pip install --python {sys.executable} {output_dir.resolve().as_posix()}")

openapi_client_codegen-0.1.7/src/openapi_client_codegen/orchestrator.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from bashrun.bash import bash_output
+from pydantic import BaseModel, ConfigDict
+
+
+class ProjectsConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    projects: dict[str, list[str]]
+    root_name: str
+    generated_root: Path
+    spec_command: str
+    spec_env: dict[str, str] | None = None
+    npm_scope: str | None = None
+    license_spdx: str | None = None
+    repository_url: str | None = None
+
+
+@dataclass(frozen=True)
+class ClientNaming:
+    base: str
+    dashed: str
+    underscored: str
+    camel: str
+
+
+class SpecProducer:
+    def __init__(self, command: str, env: dict[str, str] | None = None) -> None:
+        self.command = command
+        self.env = env
+
+    def __call__(self, project: Path) -> str:
+        return bash_output(self.command, cwd=project, env=self.env)

openapi_client_codegen-0.1.7/tests/test_cli.py

@@ -0,0 +1,107 @@
+import json
+from pathlib import Path
+
+import pytest
+from typer.testing import CliRunner
+
+from openapi_client_codegen import cli, orchestrator
+from openapi_client_codegen.cli import app
+from openapi_client_codegen.orchestrator import ClientNaming
+
+runner = CliRunner()
+
+FULL_SETTINGS: dict[str, object] = {
+    "projects": {"docker/api": ["python", "csharp"]},
+    "root_name": "placeframe",
+    "generated_root": "packages/generated",
+    "spec_command": "uv run --project . python -m src.dump_openapi",
+    "spec_env": {"CODEGEN": "1"},
+    "npm_scope": "org.example.placeframe",
+    "license_spdx": "Apache-2.0",
+    "repository_url": "https://github.com/org/repo.git",
+}
+
+
+class Recorder:
+    def __init__(self) -> None:
+        self.generated: list[tuple[str, Path]] = []
+
+    def fake_bash_output(self, command: str, *, cwd: Path | None = None, env: dict[str, str] | None = None) -> str:
+        return json.dumps({"openapi": "3.1.0", "info": {"title": "demo", "version": "0.0.0"}, "paths": {}})
+
+    def fake_regenerate_templates(self, target_dir: Path, extra_patches_dir: Path | None = None) -> None:
+        pass
+
+    def fake_generate_client(
+        self,
+        spec: str,
+        generator: str,
+        output_dir: Path,
+        names: ClientNaming,
+        templates_dir: Path | None = None,
+        extra_references: list[str] | None = None,
+        npm_scope: str | None = None,
+        license_spdx: str | None = None,
+        repository_url: str | None = None,
+    ) -> None:
+        self.generated.append((generator, output_dir))
+
+
+@pytest.fixture
+def recorder(monkeypatch: pytest.MonkeyPatch) -> Recorder:
+    recorder = Recorder()
+    monkeypatch.setattr(orchestrator, "bash_output", recorder.fake_bash_output)
+    monkeypatch.setattr(cli, "regenerate_templates", recorder.fake_regenerate_templates)
+    monkeypatch.setattr(cli, "generate_client", recorder.fake_generate_client)
+    return recorder
+
+
+def write_config(directory: Path, settings: dict[str, object]) -> Path:
+    config = directory / "clients.json"
+    config.write_text(json.dumps(settings), encoding="utf-8")
+    return config
+
+
+def test_filter_flags_restrict_generation(tmp_path: Path, recorder: Recorder) -> None:
+    config = write_config(tmp_path, FULL_SETTINGS)
+    (tmp_path / "docker" / "api").mkdir(parents=True)
+
+    result = runner.invoke(
+        app,
+        ["--config", str(config), "--root", str(tmp_path), "--project", "docker/api", "--client", "csharp"],
+    )
+
+    assert result.exit_code == 0
+    assert recorder.generated == [("csharp", Path("packages/generated") / "csharp" / "api-client")]
+
+
+def test_unknown_config_key_fails_loudly(tmp_path: Path, recorder: Recorder) -> None:
+    config = write_config(tmp_path, {"projects": {}, "rot_name": "placeframe"})
+
+    result = runner.invoke(app, ["--config", str(config)])
+
+    assert result.exit_code != 0
+    assert "rot_name" in str(result.exception)
+    assert recorder.generated == []
+
+
+def test_missing_projects_mapping_fails(tmp_path: Path, recorder: Recorder) -> None:
+    config = write_config(tmp_path, {"root_name": "placeframe"})
+
+    result = runner.invoke(app, ["--config", str(config)])
+
+    assert result.exit_code != 0
+    assert "projects" in str(result.exception)
+    assert recorder.generated == []
+
+
+def test_missing_required_field_fails(tmp_path: Path, recorder: Recorder) -> None:
+    settings = dict(FULL_SETTINGS)
+    del settings["spec_command"]
+    config = write_config(tmp_path, settings)
+
+    result = runner.invoke(app, ["--config", str(config)])
+
+    assert result.exit_code != 0
+    assert "spec_command" in str(result.exception)
+    assert recorder.generated == []