k11-api-functional-qa-mcp 0.1.0__py3-none-any.whl

k11_api_functional_qa_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: k11-api-functional-qa-mcp
+Version: 0.1.0
+Summary: MCP server and Claude Code plugin for functional API testing: user stories to multi-step API test flows, negative and boundary tests from the spec, database checks and fixtures, with evidence for every step.
+Project-URL: Homepage, https://github.com/K11-Software-Solutions/k11techlab-api-functional-qa-mcp
+Project-URL: Issues, https://github.com/K11-Software-Solutions/k11techlab-api-functional-qa-mcp/issues
+Author: K11 Software Solutions
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-testing,claude,database-testing,functional-testing,mcp,negative-testing,openapi,qa,rest
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: k11-api-contract-qa-mcp>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest-timeout>=2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: mssql
+Requires-Dist: pymssql>=2.3; extra == 'mssql'
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# k11 API Functional QA — MCP server & Claude Code plugin
+
+<!-- mcp-name: io.github.K11-Software-Solutions/api-functional-qa -->
+
+**Functional API tests that prove the API did the right thing, down to the database row.**
+
+Contract checks tell you an API still has the right *shape*. They don't tell you whether placing an order charges the right amount, whether cancelling really soft-deletes the row, or whether a malformed request crashes the server. This MCP server lets Claude (or any MCP client) write and run those tests with you:
+
+- **User story → multi-step test flow.** Chain calls (`POST /orders` → save the `id` → `GET /orders/{id}` → `DELETE`) with readable YAML and value checks.
+- **Database checks in the same flow.** After the API call, check the row really changed: `SELECT status, deleted_at FROM orders WHERE id = :orderId`. Read-only by default, with masked columns.
+- **Negative and boundary tests from the spec,** including nested fields and array items: missing required fields, wrong types, values outside enums and min/max/length limits, no credentials, unknown IDs. Every case must get a 4xx, **never a 5xx**.
+- **Evidence for every step:** the request, response, query, rows and each check, in Markdown (PR comment), JSON and JUnit XML for CI dashboards.
+- **Guardrails:** data-changing calls are refused on production-like environments, database writes only in fixtures and cleanup on allowlisted test databases, secrets only from environment variables and masked everywhere, and requests never leave the environment's host.
+- **No lock-in:** export any flow as plain pytest + httpx code.
+
+Built on the parsers of [k11 API Contract QA](https://github.com/K11-Software-Solutions/k11techlab-api-contract-qa-mcp) (OpenAPI 3.x and Swagger 2.0 for test generation and response-schema checks).
+
+---
+
+## See it find real bugs
+
+The demo shop API (`demo/shop/`) has two planted bugs. Two hand-written flows and one generated negative suite found them, plus one I didn't plant.
+
+**1. The order total is wrong only in the API response.** `order_total.yaml` orders two bags at 42.50:
+
+> ❌ **Order total is quantity times price**
+> - **place an order for two bags**: failed. Response: HTTP 201. ✗ `$.total 85.0`: expected 85.0, got 42.5
+> - **the database stores 85.00**: passed
+> - **order history shows 85.00**: passed
+
+The database check shows exactly where the bug is: the stored total is right, and only the `POST /orders` response is wrong.
+
+**2. Malformed input crashes the server.** `generate_negative_tests("POST /orders")` produced 18 cases from the spec. 16 behaved correctly, and two returned **HTTP 500**:
+
+> - ✗ wrong type for `items[0].qty` is rejected: got 500. *A 5xx is a bug.*
+> - ✗ missing required field `items[0].qty` is rejected: got 500. *A 5xx is a bug.*
+
+The second crash wasn't planted. It's the same code path, and the generator found it because it tests nested array items, not just top-level fields.
+
+**3. The soft delete works, proven in the database.** `cancel_order.yaml` passes all 7 steps, including checks that the row is kept with `status = cancelled` and a `deleted_at` timestamp.
+
+## A flow
+
+```yaml
+name: Customer cancels an order and it is soft-deleted
+fixtures: [customer]                       # seeded in the test database, removed afterwards
+steps:
+  - name: place an order
+    call: POST /orders
+    body: { customerId: "${fixture.customer.id}", channel: web, items: [{ sku: HAT-2, qty: 1 }] }
+    expect:
+      status: 201
+      json: { "$.status": pending, "$.total": 15.0, "$.items": { length: 1 } }
+    save: { orderId: "$.id" }
+
+  - name: the row is kept and marked deleted
+    db: SELECT status, deleted_at FROM orders WHERE id = :orderId
+    params: { orderId: "${orderId}" }
+    expect: { rows: 1, row: { status: cancelled, deleted_at: { ne: null } } }
+
+cleanup:
+  - db: DELETE FROM orders WHERE id = :orderId
+    params: { orderId: "${orderId}" }
+```
+
+- **Checks** (`expect`): `status` (`201`, `"2xx"`, `[400, 422]`), `json` paths (`$.items[0].qty`, `$.items[*].sku`, `$.items.length`), `headers`, `body_contains`, `max_ms`, and the response schema from the spec (on by default). Values compare as literals or with operators: `eq ne gt gte lt lte approx contains matches length type in exists empty`.
+- **Variables:** `save` from JSON paths, headers (`header:Location`) or `status`; use them as `${orderId}`. Generators: `${uuid}`, `${random_email}`, `${random_int}`, `${now}`, `${today}`. Secrets: `${ENV:NAME}`.
+- **Failures:** a step that only fails value checks lets the flow continue, to gather more evidence. A wrong status, a 5xx, a blocked write or a missing saved value stops it. `continue_on_failure: true` runs every step (generated negative suites use it). Cleanup always runs.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_environments` | Environments and whether each allows writes (and why), auth profiles, databases, fixtures, flows. |
+| `draft_flow` | User story → scenarios, the spec operations most likely involved, and a flow skeleton. |
+| `generate_negative_tests` | Negative and boundary cases for one operation, with real base values from fixtures. |
+| `write_flow` | Validates and saves a flow under `tests/api/`. |
+| `run_flows` | Runs flows (all, by path or by tag) with full evidence and reports. |
+| `call_api` | One request with the same guardrails, to explore an API while writing tests. |
+| `query_db` | One read-only query against a test database, with masking. |
+| `export_pytest` | A flow as plain pytest + httpx code. |
+
+## Configure: `.qa-mcp/api-test.yaml`
+
+```yaml
+spec: openapi.yaml
+default_environment: local
+environments:
+  local:   { base_url: http://localhost:8080 }
+  staging: { base_url: https://staging.example.com, allow_writes: true }
+  prod:    { base_url: https://api.example.com }        # read-only: writes refused
+auth:
+  default: { type: bearer, token: "${ENV:API_TOKEN}" }
+  # basic: {username, password} · api_key: {header, value} · oauth2: {token_url, client_id, client_secret, scope}
+databases:
+  main: { url: "${ENV:TEST_DB_URL}", allow_writes: true, mask: [email, card_number] }
+fixtures:
+  customer:
+    db: main
+    insert: { table: customers, values: { id: "${uuid}", email: "${random_email}", name: Test Customer } }
+    delete: { table: customers, where: { id: "${id}" } }
+```
+
+**Databases:** SQLite (built in), PostgreSQL (`pip install "k11-api-functional-qa-mcp[postgres]"`), MySQL/MariaDB (`[mysql]`) and SQL Server (`[mssql]`).
+
+## Guardrails
+
+| Risk | What happens |
+|---|---|
+| Changing data in production | `POST/PUT/PATCH/DELETE` are refused on environments named like production (`prod`, `production`, `live`) unless they set both `allow_writes: true` and `production_writes_acknowledged: true`. Other environments must be local, named like a test environment, or set `allow_writes: true`. |
+| Writing to a database | `db` steps may only read (SELECT/WITH/SHOW/EXPLAIN; no write verbs anywhere, no `FOR UPDATE`), on a read-only connection inside a rolled-back transaction. Writes happen only in fixtures and cleanup, on databases with `allow_writes: true`. |
+| SQL injection | Values go in `:named` parameters; `${...}` inside SQL text is refused, as is more than one statement. Table and column names in fixtures are validated. |
+| Leaking secrets | Credentials come from `${ENV:NAME}`. Authorization headers show as `•••`, and any secret value is masked in requests, responses, errors and reports, as are database columns listed under `mask`. |
+| Sending credentials elsewhere | Requests must stay on the environment's host; a flow can't send your token to another URL. |
+| Runaway queries | At most 1,000 rows are read per query, with timeouts on every connection and request. |
+
+## In CI
+
+```bash
+k11-api-functional-qa-mcp run --env staging
+```
+
+It writes `api-test-report.md` (PR comment), `api-test-report.json` (evidence) and `api-test-junit.xml`, sets GitHub Actions outputs and exits non-zero when a flow fails (`--fail-on any|failed|never`). See [`docs/api-tests.yml`](docs/api-tests.yml).
+
+## Install
+
+Requires Python 3.10+.
+
+```text
+/plugin marketplace add K11-Software-Solutions/k11techlab-api-functional-qa-mcp
+/plugin install api-functional-qa@k11-api-functional-qa
+```
+
+The plugin adds `/api-story-test` and `/api-negative-tests`. To add only the MCP server:
+
+```bash
+claude mcp add api-functional-qa -- uvx k11-api-functional-qa-mcp
+```
+
+Claude Desktop and other clients: run `uvx k11-api-functional-qa-mcp` with `QA_MCP_ROOT` set to your project.
+
+## Try the demo
+
+```bash
+python demo/shop/server.py --port 8080
+SHOP_URL=http://127.0.0.1:8080 SHOP_TOKEN=test-token QA_MCP_ROOT=demo/shop k11-api-functional-qa-mcp run
+```
+
+## Scope
+
+This server is for functional REST testing with database checks. Related K11 tools:
+- **Contract and breaking-change checks** (REST, GraphQL, gRPC, AsyncAPI, SOAP): [k11 API Contract QA](https://github.com/K11-Software-Solutions/k11techlab-api-contract-qa-mcp)
+- **UI tests:** [Playwright QA](https://github.com/K11-Software-Solutions/k11techlab-playwright-qa-mcp) and [Selenium QA](https://github.com/K11-Software-Solutions/k11techlab-selenium-qa-mcp)
+- **LLM red-teaming:** [LLM Assure](https://github.com/K11-Software-Solutions/k11techlab-llm-assurance-toolkit)
+
+Not covered: load testing (use k6 or Gatling) and deep fuzzing (use Schemathesis).
+
+## Development
+
+```bash
+python -m venv .venv && .venv/Scripts/pip install -e ".[dev]"   # bin/pip on macOS/Linux
+pytest   # values, guardrails, flows against the demo shop, negative tests, export, CLI, MCP (25)
+```
+
+## Roadmap
+
+- GraphQL, gRPC and SOAP calls as flow steps
+- Java export (REST Assured)
+- MongoDB checks
+- Schema-driven test data (realistic values per field format)
+
+---
+
+Built by [K11 Software Solutions](https://k11softwaresolutions.com). Part of the K11 Tech Lab agentic QA series. MIT licensed.

k11_api_functional_qa_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+k11_api_qa/__init__.py,sha256=nOwWcvfCkTMcgFP1s-lM_NQwVTDkzj9F_bCaJAIDywk,120
+k11_api_qa/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+k11_api_qa/auth.py,sha256=o5GWDqL-2MoMw4IENk1ji5w0mLG17HXG5yFq9YjaxaA,2174
+k11_api_qa/cli.py,sha256=ToB3f-ek_81sZXn319cV0_ZGtb5IBAiV6AIBMb--p4k,3325
+k11_api_qa/config.py,sha256=4p4JXNrSC-Y-uQOT3RijOrUOebL6kqsBoSQYshlUt-8,4693
+k11_api_qa/db.py,sha256=09nznjh-RwQK0wMuzbAHc06bWN8cGXXhEdq0UOoqNKo,7933
+k11_api_qa/export.py,sha256=vTMIvJDjqReg9Y1aOx4A0CIMbOwboeeIr6MUABtl3Bk,7433
+k11_api_qa/generate.py,sha256=hrYjb5goeKd9LLu6nSSvypmmGhBXEDx58gI4MToQ2BU,14600
+k11_api_qa/report.py,sha256=JQ3q-MGt2sYD7ryeHW3wjUSyzb5TuAOKwgyyRZRRDlY,5771
+k11_api_qa/runner.py,sha256=4Khy-MuYqjvil-CB7_eeqNcTYudXaU6pb_RywQTJhgI,23754
+k11_api_qa/server.py,sha256=eKtniHjbnNX68FNL9j6z9Xe7TCNxioZ7hYCTkDHfxRU,10872
+k11_api_qa/values.py,sha256=K2rK4trWcfgq49ZV22CnYiS_9Xw_sLTXSD3RMaSh9wc,9298
+k11_api_functional_qa_mcp-0.1.0.dist-info/METADATA,sha256=M5NG3n1tna41Y5r0Wase149S7dyrG0iOMjMfk3lKFBY,11186
+k11_api_functional_qa_mcp-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+k11_api_functional_qa_mcp-0.1.0.dist-info/entry_points.txt,sha256=v0IZ8h4CcJr-6dEEmYdNaxLYnF8Sh_1PXE_Mrq9mkWQ,66
+k11_api_functional_qa_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=g-8tYo5PlaRgQntQTgc7h4ECTuGrwtYuzwpMT2sKPzo,1079
+k11_api_functional_qa_mcp-0.1.0.dist-info/RECORD,,

k11_api_functional_qa_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

k11_api_functional_qa_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+k11-api-functional-qa-mcp = k11_api_qa.cli:main

k11_api_functional_qa_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 K11 Software Solutions
+
+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.

k11_api_qa/__init__.py

@@ -0,0 +1,3 @@
+"""k11 API Functional QA: multi-step API test flows with database checks, over MCP and in CI."""
+
+__version__ = "0.1.0"

k11_api_qa/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

k11_api_qa/auth.py

@@ -0,0 +1,54 @@
+"""Auth profiles: bearer, basic, api_key, oauth2 client credentials, or none.
+
+Secrets come from ``${ENV:NAME}``; they are masked in every result. OAuth tokens are cached
+for the run.
+"""
+
+from __future__ import annotations
+
+import base64
+import time
+
+import httpx
+
+from .values import Vars
+
+_cache: dict[str, tuple[str, float]] = {}
+
+
+def headers(profile_name: str | None, profiles: dict, v: Vars, timeout: float = 20) -> dict[str, str]:
+    if not profile_name or profile_name == "none":
+        return {}
+    if profile_name not in profiles:
+        if profile_name == "default":
+            return {}
+        raise ValueError(f"Unknown auth profile '{profile_name}'. Known: {sorted(profiles) or ['(none)']}")
+    p = v.sub(profiles[profile_name])
+    kind = p.get("type", "bearer")
+    if kind == "bearer":
+        return {"Authorization": f"Bearer {p['token']}"}
+    if kind == "basic":
+        raw = f"{p['username']}:{p['password']}".encode()
+        token = base64.b64encode(raw).decode()
+        v.secrets.add(token)
+        return {"Authorization": f"Basic {token}"}
+    if kind == "api_key":
+        return {p.get("header", "X-API-Key"): str(p["value"])}
+    if kind in ("oauth2", "oauth2_client_credentials"):
+        key = f"{p['token_url']}|{p['client_id']}|{p.get('scope', '')}"
+        tok, exp = _cache.get(key, ("", 0.0))
+        if not tok or exp < time.time() + 30:
+            data = {"grant_type": "client_credentials", "client_id": p["client_id"], "client_secret": p["client_secret"]}
+            if p.get("scope"):
+                data["scope"] = p["scope"]
+            if p.get("audience"):
+                data["audience"] = p["audience"]
+            r = httpx.post(p["token_url"], data=data, timeout=timeout)
+            if r.status_code >= 400:
+                raise ValueError(f"OAuth token request failed with HTTP {r.status_code}")
+            body = r.json()
+            tok = body["access_token"]
+            _cache[key] = (tok, time.time() + float(body.get("expires_in", 300)))
+        v.secrets.add(tok)
+        return {"Authorization": f"Bearer {tok}"}
+    raise ValueError(f"Unknown auth type '{kind}' (bearer, basic, api_key, oauth2)")

k11_api_qa/cli.py

@@ -0,0 +1,86 @@
+"""Command line: start the MCP server (default) or run flows in CI."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+
+USAGE = f"""k11-api-functional-qa-mcp {__version__}
+
+Usage:
+  k11-api-functional-qa-mcp                      start the MCP server on stdio
+  k11-api-functional-qa-mcp run [paths] [opts]   run API test flows and write reports
+  k11-api-functional-qa-mcp --version
+
+run options:
+  --env NAME           environment from .qa-mcp/api-test.yaml (default: default_environment)
+  --tag TAG            only flows with this tag (repeatable)
+  --report-dir PATH    default .qa-mcp/api-test-report
+  --fail-on LEVEL      any (default: fail on failed, blocked or error) | failed | never
+
+The project is QA_MCP_ROOT or the current directory.
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if not argv:
+        from .server import serve
+
+        serve()
+        return 0
+    if argv[0] in ("--version", "-v"):
+        print(__version__)
+        return 0
+    if argv[0] in ("--help", "-h", "help"):
+        print(USAGE)
+        return 0
+    if argv[0] != "run":
+        print(f"Unknown command: {argv[0]}\n\n{USAGE}", file=sys.stderr)
+        return 2
+    p = argparse.ArgumentParser(prog="k11-api-functional-qa-mcp run")
+    p.add_argument("paths", nargs="*")
+    p.add_argument("--env")
+    p.add_argument("--tag", action="append")
+    p.add_argument("--report-dir", default=".qa-mcp/api-test-report")
+    p.add_argument("--fail-on", default="any", choices=["any", "failed", "never"])
+    a = p.parse_args(argv[1:])
+
+    from k11_contract_qa.spec import SpecError, inside
+
+    from . import config, report
+    from .runner import flow_files, run_files
+
+    root = Path(os.environ.get("QA_MCP_ROOT") or os.getcwd()).resolve()
+    try:
+        cfg = config.load(root)
+        files = flow_files(root, a.paths or None)
+        if not files:
+            print("No flows found in tests/api/", file=sys.stderr)
+            return 1
+        results = run_files(cfg, files, a.env, a.tag)
+        env = results[0].environment if results else (a.env or cfg.default_environment)
+        paths = report.write(results, env, inside(root, a.report_dir))
+    except (SpecError, ValueError, OSError) as e:
+        print(f"run failed: {e}", file=sys.stderr)
+        return 1
+    c = report.counts(results)
+    print(f"{c['passed']}/{c['flows']} flows passed ({c['failed']} failed, {c['blocked']} blocked, {c['error']} errors, "
+          f"{c['server_errors']} server errors). Report: {paths['markdown']}")
+    if os.environ.get("GITHUB_OUTPUT"):
+        with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf8") as fh:
+            fh.write(f"passed={c['passed']}\nfailed={c['failed']}\nblocked={c['blocked']}\nerrors={c['error']}\n"
+                     f"report={paths['markdown']}\njunit={paths['junit']}\n")
+    if os.environ.get("GITHUB_STEP_SUMMARY"):
+        with open(os.environ["GITHUB_STEP_SUMMARY"], "a", encoding="utf8") as fh:
+            fh.write(paths["markdown"].read_text("utf8") + "\n")
+    bad = {"any": c["failed"] + c["blocked"] + c["error"], "failed": c["failed"], "never": 0}[a.fail_on]
+    return 1 if bad else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

k11_api_qa/config.py

@@ -0,0 +1,98 @@
+"""Project config: ``.qa-mcp/api-test.yaml``.
+
+    spec: openapi.yaml                       # used for schema checks and negative tests
+    default_environment: local
+    environments:
+      local:   { base_url: http://localhost:8080 }
+      staging: { base_url: https://staging.example.com, allow_writes: true }
+      prod:    { base_url: https://api.example.com }        # read-only: writes refused
+    auth:
+      default: { type: bearer, token: "${ENV:API_TOKEN}" }
+      # basic: {username, password} · api_key: {header, value} · oauth2: {token_url, client_id, client_secret, scope}
+    databases:
+      main: { url: "${ENV:TEST_DB_URL}", allow_writes: true, mask: [email] }
+    fixtures:
+      customer:
+        db: main
+        insert: { table: customers, values: { id: "${uuid}", email: "${random_email}" } }
+        delete: { table: customers, where: { id: "${id}" } }
+
+Writes (POST/PUT/PATCH/DELETE, and database writes for fixtures/cleanup) are refused on an
+environment unless it is local, its name looks like a test environment, or it sets
+``allow_writes: true``. Environments named like production never allow writes unless they
+also set ``production_writes_acknowledged: true``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+import yaml
+
+CONFIG = ".qa-mcp/api-test.yaml"
+PROD_NAME = re.compile(r"(^|[-_.])(prod|production|live|prd)([-_.]|$)", re.I)
+TEST_NAME = re.compile(r"(^|[-_.])(local|dev|test|qa|ci|staging|stage|sandbox|preview|uat)([-_.]|$)", re.I)
+LOCAL_HOST = re.compile(r"^(localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0|.*\.(localhost|test|local))$", re.I)
+
+
+@dataclass
+class Config:
+    root: Path
+    spec: str | None = None
+    default_environment: str = "local"
+    environments: dict[str, dict] = field(default_factory=dict)
+    auth: dict[str, dict] = field(default_factory=dict)
+    databases: dict[str, dict] = field(default_factory=dict)
+    fixtures: dict[str, dict] = field(default_factory=dict)
+    timeout_s: float = 30
+
+    def environment(self, name: str | None) -> tuple[str, dict]:
+        name = name or self.default_environment
+        if name not in self.environments:
+            if not self.environments and name == "local":
+                return name, {"base_url": "http://localhost:8080"}
+            raise ValueError(f"Unknown environment '{name}'. Known: {sorted(self.environments) or ['(none)']}")
+        return name, self.environments[name]
+
+
+def load(root: Path) -> Config:
+    path = Path(root) / CONFIG
+    data: dict[str, Any] = {}
+    if path.is_file():
+        data = yaml.safe_load(path.read_text("utf8")) or {}
+    return Config(root=Path(root), spec=data.get("spec"), default_environment=data.get("default_environment", "local"),
+                  environments=data.get("environments") or {}, auth=data.get("auth") or {},
+                  databases=data.get("databases") or {}, fixtures=data.get("fixtures") or {},
+                  timeout_s=float(data.get("timeout_s", 30)))
+
+
+def writes_allowed(env_name: str, env: dict, base_url: str) -> tuple[bool, str]:
+    """Whether data-changing calls may run against this environment, and why."""
+    if PROD_NAME.search(env_name):
+        if env.get("allow_writes") and env.get("production_writes_acknowledged"):
+            return True, "production writes explicitly acknowledged"
+        return False, f"'{env_name}' looks like production; writes are refused"
+    if "allow_writes" in env:
+        return bool(env["allow_writes"]), ("allow_writes: true" if env["allow_writes"] else "allow_writes: false")
+    host = urlsplit(base_url).hostname or ""
+    if LOCAL_HOST.match(host):
+        return True, "local host"
+    if TEST_NAME.search(env_name):
+        return True, f"'{env_name}' is a test environment"
+    return False, f"'{env_name}' is not marked as a test environment; set allow_writes: true to permit writes"
+
+
+def summary(cfg: Config) -> dict:
+    envs = {}
+    for name, env in cfg.environments.items():
+        ok, why = writes_allowed(name, env, str(env.get("base_url", "")))
+        envs[name] = {"base_url": env.get("base_url"), "writes": ok, "why": why, "auth": env.get("auth", "default")}
+    return {"config": CONFIG if (cfg.root / CONFIG).is_file() else None, "spec": cfg.spec,
+            "default_environment": cfg.default_environment, "environments": envs,
+            "auth_profiles": {k: v.get("type", "bearer") for k, v in cfg.auth.items()},
+            "databases": {k: {"allow_writes": bool(v.get("allow_writes")), "mask": v.get("mask", [])} for k, v in cfg.databases.items()},
+            "fixtures": sorted(cfg.fixtures)}