semblance-databricks 0.1.0__tar.gz

semblance_databricks-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Semblance Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

semblance_databricks-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: semblance-databricks
+Version: 0.1.0
+Summary: Unofficial local HTTP simulation of selected Databricks workspace REST operations
+Author: Semblance Contributors
+License-Expression: MIT
+Project-URL: Documentation, https://semblance.readthedocs.io/en/latest/guides/databricks/
+Project-URL: Repository, https://github.com/eddiethedean/semblance
+Project-URL: Changelog, https://github.com/eddiethedean/semblance/blob/main/packages/semblance-databricks/CHANGELOG.md
+Keywords: databricks,mock,simulation,testing,fastapi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: semblance<0.8,>=0.7.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: httpx>=0.25.0; extra == "dev"
+Requires-Dist: ruff>=0.16.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
+Provides-Extra: sdk
+Requires-Dist: databricks-sdk==0.57.0; extra == "sdk"
+Dynamic: license-file
+
+# semblance-databricks
+
+**Unofficial** local HTTP simulation of selected [Databricks workspace REST](https://docs.databricks.com/api/workspace/) operations (clusters, jobs, warehouses, secrets metadata, DBFS stubs, permissions, SQL statements).
+
+This package is **not affiliated with, endorsed by, or equivalent to Databricks**. It does not run Spark, jobs, or SQL engines. It is a test double for client development and CI.
+
+Verified against public workspace REST documentation dated **2026-08-19**. See `compatibility.yaml` (also served at `/.well-known/semblance-databricks-compat.json`).
+
+Requires `semblance` 0.7.x.
+
+## Install
+
+```bash
+pip install semblance-databricks
+```
+
+From a clone of this repository:
+
+```bash
+pip install -e ".[dev]"
+pip install -e "packages/semblance-databricks[dev]"
+```
+
+Optional official SDK extra (not installed in default CI):
+
+```bash
+pip install "semblance-databricks[sdk]"
+pytest packages/semblance-databricks/tests -m sdk
+```
+
+Pinned SDK: `databricks-sdk==0.57.0`. Untested SDK versions are not implied compatible.
+
+## Quick start (HTTP)
+
+```python
+from semblance_databricks import DatabricksMock, DatabricksMockConfig
+from semblance_databricks.testing import databricks_test_client
+
+dbx = DatabricksMock(DatabricksMockConfig(seed=42, auth="optional"))
+dbx.load_bundled_fixture()
+client = databricks_test_client(dbx)
+
+r = client.get("/api/2.1/clusters/list?page_size=2")
+assert r.status_code == 200
+```
+
+CLI:
+
+```bash
+semblance-databricks fixture init --output databricks.yaml
+semblance-databricks validate databricks.yaml
+semblance-databricks operations
+semblance-databricks serve --fixture databricks.yaml --port 8766
+# or: semblance-databricks serve   # bundled acme fixture
+```
+
+Environment variables for local clients (not Databricks credentials): `SEMBLANCE_DATABRICKS_HOST`, `SEMBLANCE_DATABRICKS_TOKEN`.
+
+## Auth modes
+
+- `disabled` — ignore `Authorization`
+- `optional` (default) — missing token is OK; malformed `Bearer` values return 401
+- `strict` — token must be in `DatabricksMockConfig.tokens`
+
+Authentication errors never echo the token. This is not an OAuth server.
+
+## Fixtures
+
+YAML/JSON version 1. Extra fields are rejected. Fixtures are **data only**. Secret **values** are never returned on REST (list and put only; there is no get-key).
+
+`load_bundled_fixture()` loads the shipped `acme` workspace. Use `load_fixture(path)` for your own files. Advance cluster/run state with `dbx.tick()`.
+
+## Pagination
+
+List endpoints use `page_size` or `limit` plus `page_token` / `next_page_token`. Tokens are opaque and checksummed. Tampering returns 400 `INVALID_PARAMETER_VALUE`.
+
+## Known unsupported (0.1.0)
+
+- Unity Catalog, Model Serving, DLT / Spark Declarative Pipelines
+- Jobs API 2.0 as primary (optional 2.1 aliases are representative)
+- Real Spark/SQL execution (statements use fixture or allow-listed callbacks)
+
+Unknown paths return Databricks-style 404. Known stubs such as `clusters/permanent-delete` and `dbfs/add-block` return 501 only when `auth=strict`.
+
+## Security
+
+- Do not put production secrets in fixtures or tokens used with this mock
+- Tokens are compared in-process and never written to error bodies
+- Query/SQL/run-output behavior must be allow-listed Python, never YAML eval
+
+## License
+
+MIT. Databricks is a trademark of its respective owners.

semblance_databricks-0.1.0/README.md

@@ -0,0 +1,93 @@
+# semblance-databricks
+
+**Unofficial** local HTTP simulation of selected [Databricks workspace REST](https://docs.databricks.com/api/workspace/) operations (clusters, jobs, warehouses, secrets metadata, DBFS stubs, permissions, SQL statements).
+
+This package is **not affiliated with, endorsed by, or equivalent to Databricks**. It does not run Spark, jobs, or SQL engines. It is a test double for client development and CI.
+
+Verified against public workspace REST documentation dated **2026-08-19**. See `compatibility.yaml` (also served at `/.well-known/semblance-databricks-compat.json`).
+
+Requires `semblance` 0.7.x.
+
+## Install
+
+```bash
+pip install semblance-databricks
+```
+
+From a clone of this repository:
+
+```bash
+pip install -e ".[dev]"
+pip install -e "packages/semblance-databricks[dev]"
+```
+
+Optional official SDK extra (not installed in default CI):
+
+```bash
+pip install "semblance-databricks[sdk]"
+pytest packages/semblance-databricks/tests -m sdk
+```
+
+Pinned SDK: `databricks-sdk==0.57.0`. Untested SDK versions are not implied compatible.
+
+## Quick start (HTTP)
+
+```python
+from semblance_databricks import DatabricksMock, DatabricksMockConfig
+from semblance_databricks.testing import databricks_test_client
+
+dbx = DatabricksMock(DatabricksMockConfig(seed=42, auth="optional"))
+dbx.load_bundled_fixture()
+client = databricks_test_client(dbx)
+
+r = client.get("/api/2.1/clusters/list?page_size=2")
+assert r.status_code == 200
+```
+
+CLI:
+
+```bash
+semblance-databricks fixture init --output databricks.yaml
+semblance-databricks validate databricks.yaml
+semblance-databricks operations
+semblance-databricks serve --fixture databricks.yaml --port 8766
+# or: semblance-databricks serve   # bundled acme fixture
+```
+
+Environment variables for local clients (not Databricks credentials): `SEMBLANCE_DATABRICKS_HOST`, `SEMBLANCE_DATABRICKS_TOKEN`.
+
+## Auth modes
+
+- `disabled` — ignore `Authorization`
+- `optional` (default) — missing token is OK; malformed `Bearer` values return 401
+- `strict` — token must be in `DatabricksMockConfig.tokens`
+
+Authentication errors never echo the token. This is not an OAuth server.
+
+## Fixtures
+
+YAML/JSON version 1. Extra fields are rejected. Fixtures are **data only**. Secret **values** are never returned on REST (list and put only; there is no get-key).
+
+`load_bundled_fixture()` loads the shipped `acme` workspace. Use `load_fixture(path)` for your own files. Advance cluster/run state with `dbx.tick()`.
+
+## Pagination
+
+List endpoints use `page_size` or `limit` plus `page_token` / `next_page_token`. Tokens are opaque and checksummed. Tampering returns 400 `INVALID_PARAMETER_VALUE`.
+
+## Known unsupported (0.1.0)
+
+- Unity Catalog, Model Serving, DLT / Spark Declarative Pipelines
+- Jobs API 2.0 as primary (optional 2.1 aliases are representative)
+- Real Spark/SQL execution (statements use fixture or allow-listed callbacks)
+
+Unknown paths return Databricks-style 404. Known stubs such as `clusters/permanent-delete` and `dbfs/add-block` return 501 only when `auth=strict`.
+
+## Security
+
+- Do not put production secrets in fixtures or tokens used with this mock
+- Tokens are compared in-process and never written to error bodies
+- Query/SQL/run-output behavior must be allow-listed Python, never YAML eval
+
+## License
+
+MIT. Databricks is a trademark of its respective owners.

semblance_databricks-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "semblance-databricks"
+version = "0.1.0"
+description = "Unofficial local HTTP simulation of selected Databricks workspace REST operations"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE.md"]
+authors = [{name = "Semblance Contributors"}]
+keywords = ["databricks", "mock", "simulation", "testing", "fastapi"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "semblance>=0.7.0,<0.8",
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "httpx>=0.25.0",
+    "ruff>=0.16.0",
+    "mypy>=1.0.0",
+    "types-PyYAML>=6.0.0",
+]
+sdk = [
+    "databricks-sdk==0.57.0",
+]
+
+[project.scripts]
+semblance-databricks = "semblance_databricks.cli:main"
+
+[project.urls]
+Documentation = "https://semblance.readthedocs.io/en/latest/guides/databricks/"
+Repository = "https://github.com/eddiethedean/semblance"
+Changelog = "https://github.com/eddiethedean/semblance/blob/main/packages/semblance-databricks/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+semblance_databricks = [
+    "py.typed",
+    "compatibility.yaml",
+    "fixtures/defaults/*.yaml",
+]

semblance_databricks-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

semblance_databricks-0.1.0/src/semblance_databricks/__init__.py

@@ -0,0 +1,19 @@
+"""
+Unofficial local simulation of selected Databricks workspace REST operations.
+
+Not affiliated with, endorsed by, or equivalent to Databricks.
+"""
+
+from semblance_databricks.app import DatabricksMock
+from semblance_databricks.config import DatabricksMockConfig, TokenGrant
+from semblance_databricks.fixtures.loaders import load_bundled_fixture
+from semblance_databricks.testing import DatabricksMockContext, databricks_test_client
+
+__all__ = [
+    "DatabricksMock",
+    "DatabricksMockConfig",
+    "DatabricksMockContext",
+    "TokenGrant",
+    "databricks_test_client",
+    "load_bundled_fixture",
+]

semblance_databricks-0.1.0/src/semblance_databricks/app.py

@@ -0,0 +1,104 @@
+"""DatabricksMock factory and ASGI construction."""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Callable
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as pkg_version
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI
+
+from semblance_databricks.auth import DatabricksMiddleware
+from semblance_databricks.compatibility import manifest_json
+from semblance_databricks.config import DatabricksMockConfig
+from semblance_databricks.errors import register_exception_handlers
+from semblance_databricks.fixtures.loaders import (
+    apply_fixture,
+    bundled_acme_path,
+    load_fixture_file,
+)
+from semblance_databricks.ids import PageTokenCodec, token_secret
+from semblance_databricks.services.clusters import create_clusters_router
+from semblance_databricks.services.dbfs import create_dbfs_router
+from semblance_databricks.services.dbsql import create_dbsql_router
+from semblance_databricks.services.jobs import create_jobs_router
+from semblance_databricks.services.permissions import create_permissions_router
+from semblance_databricks.services.secrets import create_secrets_router
+from semblance_databricks.services.workspace import create_workspace_router
+from semblance_databricks.state import DatabricksState
+
+_BUNDLED_FIXTURES = {"acme": bundled_acme_path}
+
+
+def _distribution_version() -> str:
+    try:
+        return pkg_version("semblance-databricks")
+    except PackageNotFoundError:
+        return "0.1.0"
+
+
+class DatabricksMock:
+    """Fixture-backed local simulation of selected Databricks REST operations."""
+
+    def __init__(self, config: DatabricksMockConfig | None = None) -> None:
+        self.config = config or DatabricksMockConfig()
+        self.state = DatabricksState(seed=self.config.seed)
+        self.page_token_codec = PageTokenCodec(token_secret(self.config.seed))
+        self._rng = random.Random(self.config.seed)
+
+    def load_fixture(self, path: str | Path) -> DatabricksMock:
+        self.state.clear()
+        doc = load_fixture_file(path)
+        apply_fixture(doc, self.state)
+        return self
+
+    def load_bundled_fixture(self, name: str = "acme") -> DatabricksMock:
+        """Load a fixture shipped with the package (currently ``acme``)."""
+        loader = _BUNDLED_FIXTURES.get(name)
+        if loader is None:
+            known = ", ".join(sorted(_BUNDLED_FIXTURES))
+            raise ValueError(
+                f"unknown bundled fixture {name!r}; expected one of: {known}"
+            )
+        return self.load_fixture(loader())
+
+    def tick(self) -> None:
+        """Advance virtual-clock cluster and run state machines."""
+        self.state.tick()
+
+    def register_statement(self, key: str, fn: Callable[..., Any]) -> None:
+        """Register an allow-listed callback keyed by SQL text or warehouse id."""
+        self.state.statement_callbacks[key] = fn
+
+    def as_fastapi(self) -> FastAPI:
+        app = FastAPI(
+            title="semblance-databricks",
+            description=(
+                "Unofficial local simulation of selected Databricks workspace "
+                "REST operations. Not affiliated with Databricks."
+            ),
+            version=_distribution_version(),
+        )
+        app.state.databricks_mock = self
+        register_exception_handlers(app)
+        app.add_middleware(
+            DatabricksMiddleware,
+            config=self.config,
+            rng=self._rng,
+        )
+        app.include_router(create_clusters_router())
+        app.include_router(create_jobs_router())
+        app.include_router(create_workspace_router())
+        app.include_router(create_dbsql_router())
+        app.include_router(create_secrets_router())
+        app.include_router(create_dbfs_router())
+        app.include_router(create_permissions_router())
+
+        @app.get("/.well-known/semblance-databricks-compat.json")
+        def compatibility() -> dict[str, Any]:
+            return manifest_json()
+
+        return app

semblance_databricks-0.1.0/src/semblance_databricks/auth.py

@@ -0,0 +1,145 @@
+"""Auth, request-id, latency, error injection, and rate-limit middleware."""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from collections import defaultdict
+from collections.abc import Callable
+from threading import Lock
+from typing import Any
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from semblance_databricks.config import DatabricksMockConfig
+from semblance_databricks.errors import databricks_error_body
+
+REQUEST_ID_HEADER = "x-databricks-request-id"
+ORG_ID_HEADER = "x-databricks-org-id"
+
+
+class _SlidingWindow:
+    def __init__(self) -> None:
+        self._timestamps: dict[tuple[str, str], list[float]] = defaultdict(list)
+        self._lock = Lock()
+
+    def allow(self, path: str, method: str, limit: float) -> bool:
+        if limit <= 0:
+            return True
+        now = time.monotonic()
+        key = (path, method)
+        with self._lock:
+            ts_list = self._timestamps[key]
+            ts_list[:] = [t for t in ts_list if now - t < 1.0]
+            if len(ts_list) >= limit:
+                return False
+            ts_list.append(now)
+        return True
+
+
+def _bearer_token(header: str | None) -> str | None:
+    if header is None or header == "":
+        return None
+    parts = header.split(None, 1)
+    if len(parts) != 2 or parts[0].lower() != "bearer":
+        raise ValueError("malformed")
+    token = parts[1].strip()
+    if not token:
+        raise ValueError("empty")
+    return token
+
+
+class DatabricksMiddleware(BaseHTTPMiddleware):
+    def __init__(
+        self,
+        app: Any,
+        config: DatabricksMockConfig,
+        rng: random.Random,
+    ) -> None:
+        super().__init__(app)
+        self._config = config
+        self._rng = rng
+        self._limiter = _SlidingWindow()
+        self._req_n = 0
+
+    async def dispatch(
+        self, request: Request, call_next: Callable[[Request], Any]
+    ) -> Response:
+        incoming = request.headers.get(REQUEST_ID_HEADER)
+        self._req_n += 1
+        request_id = incoming if incoming else f"req-{self._config.seed}-{self._req_n}"
+        request.state.request_id = request_id
+
+        if self._config.rate_limit is not None:
+            if not self._limiter.allow(
+                request.url.path, request.method, self._config.rate_limit
+            ):
+                response = JSONResponse(
+                    status_code=429,
+                    content=databricks_error_body(
+                        "REQUEST_LIMIT_EXCEEDED", "Rate limit exceeded"
+                    ),
+                )
+                self._stamp(response, request_id)
+                return response
+
+        auth_error = self._check_auth(request)
+        if auth_error is not None:
+            self._stamp(auth_error, request_id)
+            return auth_error
+
+        if self._config.latency_ms or self._config.jitter_ms:
+            delay = self._config.latency_ms / 1000.0
+            if self._config.jitter_ms:
+                delay += self._rng.uniform(0, self._config.jitter_ms) / 1000.0
+            if delay > 0:
+                await asyncio.sleep(delay)
+
+        if self._config.error_rate > 0 and self._rng.random() < self._config.error_rate:
+            codes = self._config.error_codes or [500]
+            status = self._rng.choice(codes)
+            response = JSONResponse(
+                status_code=status,
+                content=databricks_error_body("INTERNAL_ERROR", "Injected error"),
+            )
+            self._stamp(response, request_id)
+            return response
+
+        response = await call_next(request)
+        self._stamp(response, request_id)
+        return response  # type: ignore[no-any-return]
+
+    def _stamp(self, response: Response, request_id: str) -> None:
+        response.headers[REQUEST_ID_HEADER] = request_id
+        if self._config.org_id:
+            response.headers[ORG_ID_HEADER] = self._config.org_id
+
+    def _check_auth(self, request: Request) -> JSONResponse | None:
+        mode = self._config.auth
+        if mode == "disabled":
+            return None
+        header = request.headers.get("authorization")
+        try:
+            token = _bearer_token(header)
+        except ValueError:
+            return JSONResponse(
+                status_code=401,
+                content=databricks_error_body("UNAUTHENTICATED", "Invalid credentials"),
+            )
+        if mode == "optional":
+            return None
+        if token is None:
+            return JSONResponse(
+                status_code=401,
+                content=databricks_error_body("UNAUTHENTICATED", "Missing credentials"),
+            )
+        allowed = {g.token for g in self._config.tokens}
+        if token not in allowed:
+            return JSONResponse(
+                status_code=401,
+                content=databricks_error_body("UNAUTHENTICATED", "Invalid credentials"),
+            )
+        return None

semblance_databricks-0.1.0/src/semblance_databricks/cli.py

@@ -0,0 +1,112 @@
+"""CLI: serve, validate, fixture init, operations."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from semblance_databricks.app import DatabricksMock
+from semblance_databricks.config import DatabricksMockConfig
+from semblance_databricks.fixtures.loaders import bundled_acme_path, load_fixture_file
+from semblance_databricks.registry import registered_operations
+
+
+def cmd_serve(args: argparse.Namespace) -> None:
+    seed = (
+        args.seed
+        if args.seed is not None
+        else int(os.environ.get("SEMBLANCE_DATABRICKS_SEED", "42"))
+    )
+    host = os.environ.get("SEMBLANCE_DATABRICKS_HOST", args.host)
+    config = DatabricksMockConfig(seed=seed, auth=args.auth)
+    mock = DatabricksMock(config)
+    mock.load_fixture(args.fixture or bundled_acme_path())
+    app = mock.as_fastapi()
+    try:
+        import uvicorn
+    except ImportError as exc:
+        raise SystemExit(
+            "uvicorn not found. Install semblance (pulls uvicorn)."
+        ) from exc
+    uvicorn.run(app, host=host, port=args.port)
+
+
+def cmd_validate(args: argparse.Namespace) -> None:
+    try:
+        load_fixture_file(args.fixture)
+    except Exception as exc:
+        raise SystemExit(f"Invalid fixture: {exc}") from exc
+    print("OK")
+
+
+def cmd_fixture_init(args: argparse.Namespace) -> None:
+    dest = Path(args.output)
+    if dest.exists() and not args.force:
+        raise SystemExit(f"{dest} already exists (use --force to overwrite)")
+    dest.write_text(bundled_acme_path().read_text(encoding="utf-8"), encoding="utf-8")
+    print(f"Wrote {dest}")
+
+
+def cmd_operations(_args: argparse.Namespace) -> None:
+    rows = registered_operations()
+    width = max((len(op.operation_id) for op in rows), default=8)
+    print(f"{'operation':<{width}}  {'level':<16}  method  path")
+    for op in rows:
+        print(
+            f"{op.operation_id:<{width}}  {op.support_level:<16}  "
+            f"{op.method:<6}  {op.path}"
+        )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="semblance-databricks",
+        description=(
+            "Unofficial local Databricks workspace REST mock. "
+            "Not affiliated with Databricks."
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    serve = sub.add_parser("serve", help="Run a local mock server")
+    serve.add_argument(
+        "--fixture",
+        default=None,
+        help="YAML or JSON fixture path (default: bundled acme example)",
+    )
+    serve.add_argument("--host", default="127.0.0.1")
+    serve.add_argument("--port", type=int, default=8766)
+    serve.add_argument("--seed", type=int, default=None)
+    serve.add_argument(
+        "--auth",
+        default="optional",
+        choices=["disabled", "optional", "strict"],
+    )
+    serve.set_defaults(func=cmd_serve)
+
+    validate = sub.add_parser("validate", help="Validate a fixture without serving")
+    validate.add_argument("fixture")
+    validate.set_defaults(func=cmd_validate)
+
+    init = sub.add_parser("fixture", help="Fixture helpers")
+    init_sub = init.add_subparsers(dest="fixture_command", required=True)
+    init_cmd = init_sub.add_parser("init", help="Write the bundled example fixture")
+    init_cmd.add_argument("--output", required=True)
+    init_cmd.add_argument("--force", action="store_true")
+    init_cmd.set_defaults(func=cmd_fixture_init)
+
+    ops = sub.add_parser("operations", help="Print the compatibility table")
+    ops.set_defaults(func=cmd_operations)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])