feat: generate the tool catalog from the pinned swagger

Adds scripts/generate_catalog.py (with --check), the naming rules, schema conversion, the committed tools.json for all 537 operations and the load_catalog() loader.

scripts/generate_catalog.py

@@ -0,0 +1,62 @@
+"""Generate ``src/aegis_gitea_mcp/catalog/tools.json`` from ``spec/gitea-swagger.v1.json``.
+
+Usage:
+    uv run python scripts/generate_catalog.py          # write the file
+    uv run python scripts/generate_catalog.py --check  # exit 1 when the file is stale
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT / "src"))
+
+from aegis_gitea_mcp.catalog.build import diff_summary, generate  # noqa: E402
+
+SPEC_PATH = REPO_ROOT / "spec" / "gitea-swagger.v1.json"
+CATALOG_PATH = REPO_ROOT / "src" / "aegis_gitea_mcp" / "catalog" / "tools.json"
+
+
+def main(
+    argv: list[str] | None = None,
+    spec_path: Path = SPEC_PATH,
+    catalog_path: Path = CATALOG_PATH,
+) -> int:
+    """Run the generator and return the process exit code."""
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="regenerate in memory and fail when the committed file differs",
+    )
+    args = parser.parse_args(argv)
+
+    text, result = generate(spec_path)
+
+    print("operations per domain:")
+    for domain, count in result.counts.items():
+        print(f"  {domain:<13}{count}")
+    print(f"  {'total':<13}{sum(result.counts.values())}")
+    for operation_id, name in sorted(result.overrides.items()):
+        print(f"override: {operation_id} -> {name}")
+
+    if args.check:
+        committed = catalog_path.read_text("utf-8") if catalog_path.exists() else ""
+        if committed != text:
+            print(f"{catalog_path} is out of date:", file=sys.stderr)
+            print(diff_summary(committed, text), file=sys.stderr)
+            print("run: uv run python scripts/generate_catalog.py", file=sys.stderr)
+            return 1
+        print("catalog is up to date")
+        return 0
+
+    catalog_path.write_text(text, encoding="utf-8")
+    print(f"wrote {catalog_path} ({len(text.encode('utf-8'))} bytes)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())