svc-infra 0.1.604__py3-none-any.whl → 0.1.605__py3-none-any.whl

svc_infra/api/fastapi/docs/add.py

@@ -4,10 +4,13 @@ import json
 from pathlib import Path
 from typing import Optional
 
-from fastapi import FastAPI
+from fastapi import FastAPI, Request
 from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
 from fastapi.responses import HTMLResponse, JSONResponse
 
+from .landing import CardSpec, DocTargets, render_index_html
+from .scoped import DOC_SCOPES
+
 
 def add_docs(
     app: FastAPI,
@@ -16,6 +19,9 @@ def add_docs(
     swagger_url: str = "/docs",
     openapi_url: str = "/openapi.json",
     export_openapi_to: Optional[str] = None,
+    # Landing page options
+    landing_url: str = "/",
+    include_landing: bool = True,
 ) -> None:
     """Enable docs endpoints and optionally export OpenAPI schema to disk on startup.
 
@@ -29,14 +35,22 @@ def add_docs(
     app.add_api_route(openapi_url, openapi_handler, methods=["GET"], include_in_schema=False)
 
     # Swagger UI route
-    async def swagger_ui() -> HTMLResponse:  # noqa: ANN201
-        return get_swagger_ui_html(openapi_url=openapi_url, title="API Docs")
+    async def swagger_ui(request: Request) -> HTMLResponse:  # noqa: ANN201
+        resp = get_swagger_ui_html(openapi_url=openapi_url, title="API Docs")
+        theme = request.query_params.get("theme")
+        if theme == "dark":
+            return _with_dark_mode(resp)
+        return resp
 
     app.add_api_route(swagger_url, swagger_ui, methods=["GET"], include_in_schema=False)
 
     # Redoc route
-    async def redoc_ui() -> HTMLResponse:  # noqa: ANN201
-        return get_redoc_html(openapi_url=openapi_url, title="API ReDoc")
+    async def redoc_ui(request: Request) -> HTMLResponse:  # noqa: ANN201
+        resp = get_redoc_html(openapi_url=openapi_url, title="API ReDoc")
+        theme = request.query_params.get("theme")
+        if theme == "dark":
+            return _with_dark_mode(resp)
+        return resp
 
     app.add_api_route(redoc_url, redoc_ui, methods=["GET"], include_in_schema=False)
 
@@ -52,6 +66,70 @@ def add_docs(
 
         app.add_event_handler("startup", _export_docs)
 
+    # Optional landing page with the same look/feel as setup_service_api
+    if include_landing:
+        # Avoid path collision; if landing_url is already taken for GET, fallback to "/_docs"
+        existing_paths = {
+            (getattr(r, "path", None) or getattr(r, "path_format", None))
+            for r in getattr(app, "routes", [])
+            if getattr(r, "methods", None) and "GET" in r.methods
+        }
+        landing_path = landing_url or "/"
+        if landing_path in existing_paths:
+            landing_path = "/_docs"
+
+        async def _landing() -> HTMLResponse:  # noqa: ANN201
+            cards: list[CardSpec] = []
+            # Root docs card using the provided paths
+            cards.append(
+                CardSpec(
+                    tag="",
+                    docs=DocTargets(swagger=swagger_url, redoc=redoc_url, openapi_json=openapi_url),
+                )
+            )
+            # Scoped docs (if any were registered via add_prefixed_docs)
+            for scope, swagger, redoc, openapi_json, _title in DOC_SCOPES:
+                cards.append(
+                    CardSpec(
+                        tag=scope.strip("/"),
+                        docs=DocTargets(swagger=swagger, redoc=redoc, openapi_json=openapi_json),
+                    )
+                )
+            html = render_index_html(
+                service_name=app.title or "API", release=app.version or "", cards=cards
+            )
+            return HTMLResponse(html)
+
+        app.add_api_route(landing_path, _landing, methods=["GET"], include_in_schema=False)
+
+
+def _with_dark_mode(resp: HTMLResponse) -> HTMLResponse:
+    """Return a copy of the HTMLResponse with a minimal dark-theme CSS injected.
+
+    We avoid depending on custom Swagger/ReDoc builds; this works by inlining a small CSS
+    block and toggling a `.dark` class on the body element.
+    """
+    try:
+        body = resp.body.decode("utf-8", errors="ignore")
+    except Exception:  # pragma: no cover - very unlikely
+        return resp
+
+    css = _DARK_CSS
+    if "</head>" in body:
+        body = body.replace("</head>", f"<style>\n{css}\n</style></head>", 1)
+    # add class to body to allow stronger selectors
+    body = body.replace("<body>", '<body class="dark">', 1)
+    return HTMLResponse(content=body, status_code=resp.status_code, headers=dict(resp.headers))
+
+
+_DARK_CSS = """
+/* Minimal dark mode override for Swagger/ReDoc */
+@media (prefers-color-scheme: dark) { :root { color-scheme: dark; } }
+html.dark, body.dark { background: #0b0e14; color: #e0e6f1; }
+#swagger, .redoc-wrap { background: transparent; }
+a { color: #62aef7; }
+"""
+
 
 def add_sdk_generation_stub(
     app: FastAPI,

svc_infra/api/fastapi/openapi/mutators.py

@@ -1102,6 +1102,114 @@ def ensure_success_examples_mutator():
     return m
 
 
+# --- NEW: attach minimal x-codeSamples for common operations ---
+def attach_code_samples_mutator():
+    """Attach minimal curl/httpie x-codeSamples for each operation if missing.
+
+    We avoid templating parameters; samples illustrate method and path only.
+    """
+
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        servers = schema.get("servers") or [{"url": ""}]
+        base = servers[0].get("url") or ""
+
+        for path, method, op in _iter_ops(schema):
+            # Don't override existing samples
+            if isinstance(op.get("x-codeSamples"), list) and op["x-codeSamples"]:
+                continue
+            url = f"{base}{path}"
+            method_up = method.upper()
+            samples = [
+                {
+                    "lang": "bash",
+                    "label": "curl",
+                    "source": f"curl -X {method_up} '{url}'",
+                },
+                {
+                    "lang": "bash",
+                    "label": "httpie",
+                    "source": f"http {method_up} '{url}'",
+                },
+            ]
+            op["x-codeSamples"] = samples
+        return schema
+
+    return m
+
+
+# --- NEW: ensure Problem+JSON examples exist for standard error responses ---
+def ensure_problem_examples_mutator():
+    """Add example objects for 4xx/5xx responses using Problem schema if absent."""
+
+    try:
+        # Internal helper with sensible defaults
+        from .conventions import _problem_example  # type: ignore
+    except Exception:  # pragma: no cover - fallback
+
+        def _problem_example(**kw):  # type: ignore
+            base = {
+                "type": "about:blank",
+                "title": "Error",
+                "status": 500,
+                "detail": "An error occurred.",
+                "instance": "/request/trace",
+                "code": "INTERNAL_ERROR",
+            }
+            base.update(kw)
+            return base
+
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        for _, _, op in _iter_ops(schema):
+            resps = op.get("responses") or {}
+            for code, resp in resps.items():
+                if not isinstance(resp, dict):
+                    continue
+                try:
+                    ic = int(code)
+                except Exception:
+                    continue
+                if ic < 400:
+                    continue
+                content = resp.setdefault("content", {})
+                # prefer problem+json but also set application/json if present
+                for mt in ("application/problem+json", "application/json"):
+                    mt_obj = content.get(mt)
+                    if mt_obj is None:
+                        # Create a basic media type referencing Problem schema when appropriate
+                        if mt == "application/problem+json":
+                            mt_obj = {"schema": {"$ref": "#/components/schemas/Problem"}}
+                            content[mt] = mt_obj
+                        else:
+                            continue
+                    if not isinstance(mt_obj, dict):
+                        continue
+                    if "example" in mt_obj or "examples" in mt_obj:
+                        continue
+                    mt_obj["example"] = _problem_example(status=ic)
+        return schema
+
+    return m
+
+
+# --- NEW: attach default tags from first path segment when missing ---
+def attach_default_tags_mutator():
+    """If an operation has no tags, tag it by its first path segment."""
+
+    def m(schema: dict) -> dict:
+        schema = dict(schema)
+        for path, _method, op in _iter_ops(schema):
+            tags = op.get("tags")
+            if tags:
+                continue
+            seg = path.strip("/").split("/", 1)[0] or "root"
+            op["tags"] = [seg]
+        return schema
+
+    return m
+
+
 def dedupe_tags_mutator():
     def m(schema: dict) -> dict:
         schema = dict(schema)
@@ -1429,6 +1537,9 @@ def setup_mutators(
         ensure_media_type_schemas_mutator(),
         ensure_examples_for_json_mutator(),
         ensure_success_examples_mutator(),
+        attach_default_tags_mutator(),
+        attach_code_samples_mutator(),
+        ensure_problem_examples_mutator(),
         ensure_media_examples_mutator(),
         scrub_invalid_object_examples_mutator(),
         normalize_no_content_204_mutator(),

svc_infra/billing/__init__.py

@@ -0,0 +1,23 @@
+from .models import (
+    Invoice,
+    InvoiceLine,
+    Plan,
+    PlanEntitlement,
+    Price,
+    Subscription,
+    UsageAggregate,
+    UsageEvent,
+)
+from .service import BillingService
+
+__all__ = [
+    "UsageEvent",
+    "UsageAggregate",
+    "Plan",
+    "PlanEntitlement",
+    "Subscription",
+    "Price",
+    "Invoice",
+    "InvoiceLine",
+    "BillingService",
+]

svc_infra/billing/models.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import JSON, DateTime, Index, Numeric, String, UniqueConstraint, text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from svc_infra.db.sql.base import ModelBase
+
+TENANT_ID_LEN = 64
+
+
+class UsageEvent(ModelBase):
+    __tablename__ = "billing_usage_events"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(TENANT_ID_LEN), index=True, nullable=False)
+    metric: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    amount: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    at_ts: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    idempotency_key: Mapped[str] = mapped_column(String(128), nullable=False)
+    metadata_json: Mapped[dict] = mapped_column(JSON, default=dict)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )
+
+    __table_args__ = (
+        UniqueConstraint("tenant_id", "metric", "idempotency_key", name="uq_usage_idem"),
+        Index("ix_usage_tenant_metric_ts", "tenant_id", "metric", "at_ts"),
+    )
+
+
+class UsageAggregate(ModelBase):
+    __tablename__ = "billing_usage_aggregates"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(TENANT_ID_LEN), index=True, nullable=False)
+    metric: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    period_start: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    granularity: Mapped[str] = mapped_column(String(8), nullable=False)  # hour|day|month
+    total: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )
+
+    __table_args__ = (
+        UniqueConstraint("tenant_id", "metric", "period_start", "granularity", name="uq_usage_agg"),
+    )
+
+
+class Plan(ModelBase):
+    __tablename__ = "billing_plans"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    key: Mapped[str] = mapped_column(String(64), unique=True, index=True, nullable=False)
+    name: Mapped[str] = mapped_column(String(128), nullable=False)
+    description: Mapped[Optional[str]] = mapped_column(String(255))
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )
+
+
+class PlanEntitlement(ModelBase):
+    __tablename__ = "billing_plan_entitlements"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    plan_id: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    key: Mapped[str] = mapped_column(String(64), nullable=False)
+    limit_per_window: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    window: Mapped[str] = mapped_column(String(8), nullable=False)  # day|month
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )
+
+
+class Subscription(ModelBase):
+    __tablename__ = "billing_subscriptions"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(TENANT_ID_LEN), index=True, nullable=False)
+    plan_id: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    effective_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    ended_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )
+
+
+class Price(ModelBase):
+    __tablename__ = "billing_prices"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    key: Mapped[str] = mapped_column(String(64), unique=True, index=True, nullable=False)
+    currency: Mapped[str] = mapped_column(String(8), nullable=False)
+    unit_amount: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)  # minor units
+    metric: Mapped[Optional[str]] = mapped_column(String(64))  # null for fixed recurring
+    recurring_interval: Mapped[Optional[str]] = mapped_column(String(8))  # month|year
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )
+
+
+class Invoice(ModelBase):
+    __tablename__ = "billing_invoices"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(TENANT_ID_LEN), index=True, nullable=False)
+    period_start: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    period_end: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    status: Mapped[str] = mapped_column(String(16), index=True, nullable=False)
+    total_amount: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    currency: Mapped[str] = mapped_column(String(8), nullable=False)
+    provider_invoice_id: Mapped[Optional[str]] = mapped_column(String(128), index=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )
+
+
+class InvoiceLine(ModelBase):
+    __tablename__ = "billing_invoice_lines"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    invoice_id: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    price_id: Mapped[Optional[str]] = mapped_column(String(64), index=True)
+    metric: Mapped[Optional[str]] = mapped_column(String(64))
+    quantity: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    amount: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )

svc_infra/billing/service.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Callable, Optional
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from .models import Invoice, InvoiceLine, UsageAggregate, UsageEvent
+
+ProviderSyncHook = Callable[[Invoice, list[InvoiceLine]], None]
+
+
+@dataclass
+class BillingService:
+    session: Session
+    tenant_id: str
+    provider_sync: Optional[ProviderSyncHook] = None
+
+    def record_usage(
+        self, *, metric: str, amount: int, at: datetime, idempotency_key: str, metadata: dict | None
+    ) -> str:
+        # Ensure UTC
+        if at.tzinfo is None:
+            at = at.replace(tzinfo=timezone.utc)
+        evt = UsageEvent(
+            id=str(uuid.uuid4()),
+            tenant_id=self.tenant_id,
+            metric=metric,
+            amount=amount,
+            at_ts=at,
+            idempotency_key=idempotency_key,
+            metadata_json=metadata or {},
+        )
+        self.session.add(evt)
+        self.session.flush()
+        return evt.id
+
+    def aggregate_daily(self, *, metric: str, day_start: datetime) -> None:
+        # Compute [day_start, day_start+1d)
+        next_day = day_start.replace(hour=0, minute=0, second=0, microsecond=0) + timedelta(days=1)
+        total = 0
+        rows = self.session.execute(
+            select(UsageEvent).where(
+                UsageEvent.tenant_id == self.tenant_id,
+                UsageEvent.metric == metric,
+                UsageEvent.at_ts >= day_start,
+                UsageEvent.at_ts < next_day,
+            )
+        ).scalars()
+        for r in rows:
+            total += int(r.amount)
+        # upsert aggregate
+        agg = self.session.execute(
+            select(UsageAggregate).where(
+                UsageAggregate.tenant_id == self.tenant_id,
+                UsageAggregate.metric == metric,
+                UsageAggregate.period_start == day_start,
+                UsageAggregate.granularity == "day",
+            )
+        ).scalar_one_or_none()
+        if agg:
+            agg.total = total
+        else:
+            self.session.add(
+                UsageAggregate(
+                    id=str(uuid.uuid4()),
+                    tenant_id=self.tenant_id,
+                    metric=metric,
+                    period_start=day_start,
+                    granularity="day",
+                    total=total,
+                )
+            )
+
+    def generate_monthly_invoice(
+        self, *, period_start: datetime, period_end: datetime, currency: str
+    ) -> str:
+        # Minimal: sum all daily aggregates and produce one line
+        total = 0
+        rows = self.session.execute(
+            select(UsageAggregate).where(
+                UsageAggregate.tenant_id == self.tenant_id,
+                UsageAggregate.period_start >= period_start,
+                UsageAggregate.period_start < period_end,
+                UsageAggregate.granularity == "day",
+            )
+        ).scalars()
+        for r in rows:
+            total += int(r.total)
+        inv = Invoice(
+            id=str(uuid.uuid4()),
+            tenant_id=self.tenant_id,
+            period_start=period_start,
+            period_end=period_end,
+            status="created",
+            total_amount=total,
+            currency=currency,
+        )
+        self.session.add(inv)
+        self.session.flush()
+        line = InvoiceLine(
+            id=str(uuid.uuid4()),
+            invoice_id=inv.id,
+            price_id=None,
+            metric=None,
+            quantity=1,
+            amount=total,
+        )
+        self.session.add(line)
+        if self.provider_sync:
+            self.provider_sync(inv, [line])
+        return inv.id

svc_infra/cli/__init__.py

@@ -6,9 +6,11 @@ from svc_infra.cli.cmds import (
     _HELP,
     jobs_app,
     register_alembic,
+    register_dx,
     register_mongo,
     register_mongo_scaffold,
     register_obs,
+    register_sdk,
     register_sql_export,
     register_sql_scaffold,
 )
@@ -29,9 +31,15 @@ register_mongo_scaffold(app)
 # -- observability commands ---
 register_obs(app)
 
+# -- dx commands ---
+register_dx(app)
+
 # -- jobs commands ---
 app.add_typer(jobs_app, name="jobs")
 
+# -- sdk commands ---
+register_sdk(app)
+
 
 def main():
     app()

svc_infra/cli/cmds/__init__.py

@@ -5,8 +5,10 @@ from svc_infra.cli.cmds.db.nosql.mongo.mongo_scaffold_cmds import (
 from svc_infra.cli.cmds.db.sql.alembic_cmds import register as register_alembic
 from svc_infra.cli.cmds.db.sql.sql_export_cmds import register as register_sql_export
 from svc_infra.cli.cmds.db.sql.sql_scaffold_cmds import register as register_sql_scaffold
+from svc_infra.cli.cmds.dx import register_dx
 from svc_infra.cli.cmds.jobs.jobs_cmds import app as jobs_app
 from svc_infra.cli.cmds.obs.obs_cmds import register as register_obs
+from svc_infra.cli.cmds.sdk.sdk_cmds import register as register_sdk
 
 from .help import _HELP
 
@@ -18,5 +20,7 @@ __all__ = [
     "register_mongo_scaffold",
     "register_obs",
     "jobs_app",
+    "register_sdk",
+    "register_dx",
     "_HELP",
 ]

svc_infra/cli/cmds/dx/__init__.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import typer
+
+from .dx_cmds import app as dx_app
+
+
+def register_dx(root: typer.Typer) -> None:
+    root.add_typer(dx_app, name="dx")
+
+
+__all__ = ["register_dx"]

svc_infra/cli/cmds/dx/dx_cmds.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+
+from svc_infra.dx.changelog import Commit, generate_release_section
+from svc_infra.dx.checks import check_migrations_up_to_date, check_openapi_problem_schema
+
+app = typer.Typer(no_args_is_help=True, add_completion=False)
+
+
+@app.command("openapi")
+def cmd_openapi(path: str = typer.Argument(..., help="Path to OpenAPI JSON")):
+    try:
+        check_openapi_problem_schema(path=path)
+    except Exception as e:  # noqa: BLE001
+        typer.secho(f"OpenAPI check failed: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(2)
+    typer.secho("OpenAPI checks passed", fg=typer.colors.GREEN)
+
+
+@app.command("migrations")
+def cmd_migrations(project_root: str = typer.Option(".", help="Project root")):
+    try:
+        check_migrations_up_to_date(project_root=project_root)
+    except Exception as e:  # noqa: BLE001
+        typer.secho(f"Migrations check failed: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(2)
+    typer.secho("Migrations checks passed", fg=typer.colors.GREEN)
+
+
+@app.command("changelog")
+def cmd_changelog(
+    version: str = typer.Argument(..., help="Version (e.g., 0.1.604)"),
+    commits_file: str = typer.Option(None, help="Path to JSON lines of commits (sha,subject)"),
+):
+    """Generate a changelog section from commit messages.
+
+    Expects Conventional Commits style for best grouping; falls back to Other.
+    If commits_file is omitted, prints an example format.
+    """
+    import json
+    import sys
+
+    if not commits_file:
+        typer.echo(
+            '# Provide --commits-file with JSONL: {"sha": "<sha>", "subject": "feat: ..."}',
+            err=True,
+        )
+        raise typer.Exit(2)
+    rows = [
+        json.loads(line) for line in Path(commits_file).read_text().splitlines() if line.strip()
+    ]
+    commits = [Commit(sha=r["sha"], subject=r["subject"]) for r in rows]
+    out = generate_release_section(version=version, commits=commits)
+    sys.stdout.write(out)
+
+
+@app.command("ci")
+def cmd_ci(
+    run: bool = typer.Option(False, help="Execute the steps; default just prints a plan"),
+    openapi: str | None = typer.Option(None, help="Path to OpenAPI JSON to lint"),
+    project_root: str = typer.Option(".", help="Project root for migrations check"),
+):
+    """Print (or run) the CI steps locally to mirror the workflow."""
+    steps: list[list[str]] = []
+    # Lint, typecheck, tests
+    steps.append(["flake8", "--select=E,F"])  # mirrors CI
+    steps.append(["mypy", "src"])  # mirrors CI
+    if openapi:
+        steps.append([sys.executable, "-m", "svc_infra.cli", "dx", "openapi", openapi])
+    steps.append(
+        [sys.executable, "-m", "svc_infra.cli", "dx", "migrations", "--project-root", project_root]
+    )
+    steps.append(["pytest", "-q", "-W", "error"])  # mirrors CI
+
+    if not run:
+        typer.echo("CI dry-run plan:")
+        for cmd in steps:
+            typer.echo("  $ " + " ".join(cmd))
+        return
+
+    import subprocess
+
+    for cmd in steps:
+        typer.echo("Running: " + " ".join(cmd))
+        res = subprocess.run(cmd)
+        if res.returncode != 0:
+            raise typer.Exit(res.returncode)
+    typer.echo("All CI steps passed")
+
+
+def main():  # pragma: no cover - CLI entrypoint
+    app()
+
+
+__all__ = ["main", "app"]

svc_infra/cli/cmds/sdk/sdk_cmds.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import subprocess
+
+import typer
+
+app = typer.Typer(no_args_is_help=True, add_completion=False, help="Generate SDKs from OpenAPI.")
+
+
+def _echo(cmd: list[str]):
+    typer.echo("$ " + " ".join(cmd))
+
+
+def _parse_bool(val: str | bool | None, default: bool = True) -> bool:
+    if isinstance(val, bool):
+        return val
+    if val is None:
+        return default
+    s = str(val).strip().lower()
+    if s in {"1", "true", "yes", "y"}:
+        return True
+    if s in {"0", "false", "no", "n"}:
+        return False
+    return default
+
+
+@app.command("ts")
+def sdk_ts(
+    openapi: str = typer.Argument(..., help="Path to OpenAPI JSON"),
+    outdir: str = typer.Option("sdk-ts", help="Output directory"),
+    dry_run: str = typer.Option("true", help="Print commands instead of running (true/false)"),
+):
+    """Generate a TypeScript SDK (openapi-typescript-codegen as default)."""
+    cmd = [
+        "npx",
+        "openapi-typescript-codegen",
+        "--input",
+        openapi,
+        "--output",
+        outdir,
+    ]
+    if _parse_bool(dry_run, True):
+        _echo(cmd)
+        return
+    subprocess.check_call(cmd)
+    typer.secho(f"TS SDK generated → {outdir}", fg=typer.colors.GREEN)
+
+
+@app.command("py")
+def sdk_py(
+    openapi: str = typer.Argument(..., help="Path to OpenAPI JSON"),
+    outdir: str = typer.Option("sdk-py", help="Output directory"),
+    package_name: str = typer.Option("client_sdk", help="Python package name"),
+    dry_run: str = typer.Option("true", help="Print commands instead of running (true/false)"),
+):
+    """Generate a Python SDK via openapi-generator-cli with "python" generator."""
+    cmd = [
+        "npx",
+        "-y",
+        "@openapitools/openapi-generator-cli",
+        "generate",
+        "-i",
+        openapi,
+        "-g",
+        "python",
+        "-o",
+        outdir,
+        "--additional-properties",
+        f"packageName={package_name}",
+    ]
+    if _parse_bool(dry_run, True):
+        _echo(cmd)
+        return
+    subprocess.check_call(cmd)
+    typer.secho(f"Python SDK generated → {outdir}", fg=typer.colors.GREEN)
+
+
+@app.command("postman")
+def sdk_postman(
+    openapi: str = typer.Argument(..., help="Path to OpenAPI JSON"),
+    out: str = typer.Option("postman_collection.json", help="Output Postman collection"),
+    dry_run: str = typer.Option("true", help="Print commands instead of running (true/false)"),
+):
+    """Convert OpenAPI to a Postman collection via openapi-to-postmanv2."""
+    cmd = [
+        "npx",
+        "-y",
+        "openapi-to-postmanv2",
+        "-s",
+        openapi,
+        "-o",
+        out,
+    ]
+    if _parse_bool(dry_run, True):
+        _echo(cmd)
+        return
+    subprocess.check_call(cmd)
+    typer.secho(f"Postman collection generated → {out}", fg=typer.colors.GREEN)
+
+
+def register(root: typer.Typer):
+    root.add_typer(app, name="sdk")

svc_infra/dx/changelog.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date as _date
+from typing import Sequence
+
+
+@dataclass(frozen=True)
+class Commit:
+    sha: str
+    subject: str
+
+
+_SECTION_ORDER = [
+    ("feat", "Features"),
+    ("fix", "Bug Fixes"),
+    ("perf", "Performance"),
+    ("refactor", "Refactors"),
+]
+
+
+def _classify(subject: str) -> tuple[str, str]:
+    """Return (type, title) where title is display name of the section."""
+    lower = subject.strip().lower()
+    for t, title in _SECTION_ORDER:
+        if lower.startswith(t + ":") or lower.startswith(t + "("):
+            return (t, title)
+    return ("other", "Other")
+
+
+def _format_item(commit: Commit) -> str:
+    subj = commit.subject.strip()
+    # Strip leading type(scope): if present
+    i = subj.find(": ")
+    if i != -1 and i < 20:  # conventional commit prefix
+        pretty = subj[i + 2 :].strip()
+    else:
+        pretty = subj
+    return f"- {pretty} ({commit.sha})"
+
+
+def generate_release_section(
+    *,
+    version: str,
+    commits: Sequence[Commit],
+    release_date: str | None = None,
+) -> str:
+    """Generate a markdown release section from commits.
+
+    Group by type: feat, fix, perf, refactor; everything else under Other.
+    """
+    if release_date is None:
+        release_date = _date.today().isoformat()
+
+    buckets: dict[str, list[str]] = {k: [] for k, _ in _SECTION_ORDER}
+    buckets["other"] = []
+
+    for c in commits:
+        typ, _ = _classify(c.subject)
+        buckets.setdefault(typ, []).append(_format_item(c))
+
+    lines: list[str] = [f"## v{version} - {release_date}", ""]
+    for key, title in _SECTION_ORDER + [("other", "Other")]:
+        items = buckets.get(key) or []
+        if not items:
+            continue
+        lines.append(f"### {title}")
+        lines.extend(items)
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+__all__ = ["Commit", "generate_release_section"]

svc_infra/dx/checks.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _load_json(path: str | Path) -> dict:
+    import json
+
+    p = Path(path)
+    return json.loads(p.read_text())
+
+
+def check_openapi_problem_schema(
+    schema: dict | None = None, *, path: str | Path | None = None
+) -> None:
+    """Validate OpenAPI has a Problem schema with required fields and formats.
+
+    Raises ValueError with a descriptive message on failure.
+    """
+
+    if schema is None:
+        if path is None:
+            raise ValueError("either schema or path must be provided")
+        schema = _load_json(path)
+
+    comps = (schema or {}).get("components") or {}
+    prob = (comps.get("schemas") or {}).get("Problem")
+    if not isinstance(prob, dict):
+        raise ValueError("Problem schema missing under components.schemas.Problem")
+
+    props = prob.get("properties") or {}
+    # Required keys presence
+    for key in ("type", "title", "status", "detail", "instance", "code"):
+        if key not in props:
+            raise ValueError(f"Problem.{key} missing in properties")
+
+    # instance must be uri-reference per our convention
+    inst = props.get("instance") or {}
+    if inst.get("format") != "uri-reference":
+        raise ValueError("Problem.instance must have format 'uri-reference'")
+
+
+def check_migrations_up_to_date(*, project_root: str | Path = ".") -> None:
+    """Best-effort migrations check: passes if alembic env present and head is reachable.
+
+    This is a lightweight stub that can be extended per-project. For now, it checks
+    that an Alembic env exists when 'alembic.ini' is present; it does not execute DB calls.
+    """
+
+    root = Path(project_root)
+    # If alembic.ini is absent, there's nothing to check here
+    if not (root / "alembic.ini").exists():
+        return
+    # Ensure versions/ dir exists under migrations path if configured, default to 'migrations'
+    mig_dir = root / "migrations"
+    if not mig_dir.exists():
+        # tolerate alternative layout via env; keep stub permissive
+        return
+    versions = mig_dir / "versions"
+    if not versions.exists():
+        raise ValueError("Alembic migrations directory missing versions/ subfolder")
+
+
+__all__ = [
+    "check_openapi_problem_schema",
+    "check_migrations_up_to_date",
+]

{svc_infra-0.1.604.dist-info → svc_infra-0.1.605.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: svc-infra
-Version: 0.1.604
+Version: 0.1.605
 Summary: Infrastructure for building and deploying prod-ready services
 License: MIT
 Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic
@@ -94,6 +94,7 @@ svc-infra packages the shared building blocks we use to ship production FastAPI
 | Ops | Probes, breaker, SLOs & dashboards | [SLOs & Ops](docs/ops.md) |
 | Webhooks | Subscription store, signing, retry worker | [Webhooks framework](docs/webhooks.md) |
 | Security | Password policy, lockout, signed cookies, headers | [Security hardening](docs/security.md) |
+| Contributing | Dev setup and quality gates | [Contributing guide](docs/contributing.md) |
 | Data Lifecycle | Fixtures, retention, erasure, backups | [Data lifecycle](docs/data-lifecycle.md) |
 
 ## Minimal FastAPI bootstrap

{svc_infra-0.1.604.dist-info → svc_infra-0.1.605.dist-info}/RECORD

@@ -56,7 +56,7 @@ svc_infra/api/fastapi/db/sql/session.py,sha256=DUBqKTRJAX4fqRz9B-w9eD9SpzZ8EUS86
 svc_infra/api/fastapi/db/sql/users.py,sha256=68HGJgYVTEjKJm4-DPPC8-6nwXJoCukmgrYIIOHEUjs,5346
 svc_infra/api/fastapi/dependencies/ratelimit.py,sha256=DiOC-MJfqTtSydM6RAaeAsiXXL_6oZQoBLvRSpdWzs4,3794
 svc_infra/api/fastapi/docs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-svc_infra/api/fastapi/docs/add.py,sha256=Ytk4iqWrNqPg3-SELJ5OUNuTieltpTBmIFOPKGnHVag,2563
+svc_infra/api/fastapi/docs/add.py,sha256=41asodVG_0Iokl9dpcGGmFO8z5ak3gNRmsmx6rNHnaM,5689
 svc_infra/api/fastapi/docs/landing.py,sha256=5JqJYCxQDCWy-BeDLfkv7OBlzWQKSGWUCYXQ51hojG8,4627
 svc_infra/api/fastapi/docs/scoped.py,sha256=AuN35Op-9fUvHQCLOBtRjd5eWSpB5C9EAW_7-Boxmfo,7540
 svc_infra/api/fastapi/dual/__init__.py,sha256=scHLcNFkGbgX_R21V702xnAv6GMCkQ4n7yUtNDNgliM,552
@@ -88,7 +88,7 @@ svc_infra/api/fastapi/openapi/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5N
 svc_infra/api/fastapi/openapi/apply.py,sha256=VAwRfcYSLCSKIpO1dp9okG1MXvkZuciU41jrSSuvUpI,1697
 svc_infra/api/fastapi/openapi/conventions.py,sha256=e6gUsFyfEGvz3KkUimjAWMfF7_fonMJ3IoGvQZjpvfs,7171
 svc_infra/api/fastapi/openapi/models.py,sha256=MmXMpPZQjZygajfIHaL4_3q0zluPtpRevsSyOIiE83Y,2562
-svc_infra/api/fastapi/openapi/mutators.py,sha256=KcWnJ3dsn_VdBG-x0ytddf_vwJ6u-84O9V2vPxQ5Nqk,51307
+svc_infra/api/fastapi/openapi/mutators.py,sha256=0bSKVPw-lDA3L_vaPDhcM0rC7xKS-XNTzgR8hxxoM18,55266
 svc_infra/api/fastapi/openapi/pipeline.py,sha256=GAf-qzwmWlYbrAlPirr8w89fEO4-kFrhCoeMj-7mE44,646
 svc_infra/api/fastapi/openapi/responses.py,sha256=pBUoJd0lltBkQBJACS1Zd1wd975gbw6dYyMEqyueRuw,1093
 svc_infra/api/fastapi/openapi/security.py,sha256=U78KMwgc7FilFPLbIE2f6xrp74hq6TDFXpUMGRyK_bg,1248
@@ -112,6 +112,9 @@ svc_infra/app/logging/add.py,sha256=D5wYNYqnhzsh3MVWXzN6ORY5I0cGw5ZdRbEH3ljpi50,
 svc_infra/app/logging/filter.py,sha256=lPHUoCFoTP5AfwORCvwVe5z2Kltb0MwAXANwrcBAIdE,1992
 svc_infra/app/logging/formats.py,sha256=65eHUMWj7aD1RG7lCYIBSkFa_B748TutrZsta0OS_-8,4657
 svc_infra/app/root.py,sha256=344EWBMJCduwzJ1BBo0yGAu15TkryuvOW4qBZ6Gk-8w,1635
+svc_infra/billing/__init__.py,sha256=AdVxgBWibsz0xWk-Z91B7HecA-EhPMSRrXWIYPBgtMA,365
+svc_infra/billing/models.py,sha256=bnCGPKfnK__6x0f0bwKYQsG2GwXjJFi3YRXnq5JYs7c,6083
+svc_infra/billing/service.py,sha256=3SDpPA3NF2lMYiOP4U99sgXpZAXaauexBfZQmYE2kvU,3727
 svc_infra/cache/README.md,sha256=ZgIpmE0UVlGktp2nXUYv6FKJATCdkR_01v-GGxHN6Ao,10795
 svc_infra/cache/__init__.py,sha256=Fz3NS81jrY5sLikRhITCeHDT4MlOLcbMed5EjVecSAg,956
 svc_infra/cache/backend.py,sha256=Vrza_8oi1AYUG1KdFmxg8S11WB4rKpKI246fZn4pdWs,4233
@@ -123,9 +126,9 @@ svc_infra/cache/resources.py,sha256=BhvPAZvCQ-fitUdniGEOOE4g1ZvljdCA_R5pR8WfJz4,
 svc_infra/cache/tags.py,sha256=9URw4BRlnb4QFAYpDI36fMms6642xq4TeV9jqsEjzE8,2625
 svc_infra/cache/ttl.py,sha256=_lWvNx1CTE4RcFEOUYkADd7_k4I13SLmtK0AMRUq2OM,1945
 svc_infra/cache/utils.py,sha256=-LWr5IiJCNm3pwaoeCVlxNknnO2ChNKFcAGlFU98kjg,4856
-svc_infra/cli/__init__.py,sha256=rWsQDwgYVZifCP0tgB8DKm0uPSX56qd9ipiYsVwD-eM,749
+svc_infra/cli/__init__.py,sha256=Bdmx-qMHwPINg1S6nIsU7f4Qfrg8QmDiIQ11BblEuL4,864
 svc_infra/cli/__main__.py,sha256=5BjNuyet8AY-POwoF5rGt722rHQ7tJ0Vf0UFUfzzi-I,58
-svc_infra/cli/cmds/__init__.py,sha256=wlWXa2PPxfmARkqEDQODhjCBrGJoti9eX8eE1IruX7w,804
+svc_infra/cli/cmds/__init__.py,sha256=MqXFdhTyLHua-c0bJGm0O5kFKsS-TXrA48PJy5u5zFU,958
 svc_infra/cli/cmds/db/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/cli/cmds/db/nosql/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/cli/cmds/db/nosql/mongo/README.md,sha256=0u3XLeoBd0XQzXwwfEiFISMIij11TJ9iOGzrysBvsFk,1788
@@ -136,11 +139,15 @@ svc_infra/cli/cmds/db/sql/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJW
 svc_infra/cli/cmds/db/sql/alembic_cmds.py,sha256=HfnLsLJMug6llfitiwUvwdrXzcjRqrn-BVyJNcQDLFA,8519
 svc_infra/cli/cmds/db/sql/sql_export_cmds.py,sha256=6MxoQO-9upoXg0cl1RHIqz96yXFVGidiBYp_ewhB0E0,2700
 svc_infra/cli/cmds/db/sql/sql_scaffold_cmds.py,sha256=eNTCqHXOxgl9H3WTbGVn9BHXYwCpjIEJsDqhEFdrYMM,4613
+svc_infra/cli/cmds/dx/__init__.py,sha256=wQtl3-kOgoESlpVkjl3YFtqkOnQSIvVsOdutiaZFejM,197
+svc_infra/cli/cmds/dx/dx_cmds.py,sha256=XTKUJzS3UIYn6h3CHzDEWKYJaWn0TzGiUCq3OeW27E0,3326
 svc_infra/cli/cmds/help.py,sha256=wGfZFMYaR2ZPwW2JwKDU7M3m4AtdCd8GRQ412AmEBUM,758
 svc_infra/cli/cmds/jobs/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
 svc_infra/cli/cmds/jobs/jobs_cmds.py,sha256=l-w5GuR82GWR_F1CA7WPYAM895XBD8TQj_hZ6retBv0,1252
 svc_infra/cli/cmds/obs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/cli/cmds/obs/obs_cmds.py,sha256=fltUZu5fcnZdl0_JPJBIxIaA1Xqpw1BXE-SWBP-PRuY,6485
+svc_infra/cli/cmds/sdk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+svc_infra/cli/cmds/sdk/sdk_cmds.py,sha256=xzEbhA-L5bXMxf-DFzYXkdITfC4ua1Lt8I9x6PoEax0,2886
 svc_infra/cli/foundation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/cli/foundation/runner.py,sha256=RbfjKwb3aHk1Y0MYU8xMpKRpIqRVMVr8GuL2EDZ6n38,1862
 svc_infra/cli/foundation/typer_bootstrap.py,sha256=KapgH1R-qON9FuYH1KYlVx_5sJvjmAGl25pB61XCpm4,985
@@ -206,6 +213,8 @@ svc_infra/db/sql/utils.py,sha256=nzuDcDhnVNehx5Y9BZLgxw8fvpfYbxTfXQsgnznVf4w,328
 svc_infra/db/sql/versioning.py,sha256=okZu2ad5RAFXNLXJgGpcQvZ5bc6gPjRWzwiBT0rEJJw,400
 svc_infra/db/utils.py,sha256=aTD49VJSEu319kIWJ1uijUoP51co4lNJ3S0_tvuyGio,802
 svc_infra/dx/add.py,sha256=FAnLGP0BPm_q_VCEcpUwfj-b0mEse988chh9DHeS7GU,1474
+svc_infra/dx/changelog.py,sha256=9SD29ZzKzbGTA6kHQXiPLtb7uueL1wrRiiLE2qMzz8o,1941
+svc_infra/dx/checks.py,sha256=R6YqRvpKPr9zQgif4QVx2_Zl4s9YjehSkAvwlxK46lI,2267
 svc_infra/jobs/builtins/outbox_processor.py,sha256=VZoehNyjdaV_MmV74WMcbZR6z9E3VFMtZC-pxEwK0x0,1247
 svc_infra/jobs/builtins/webhook_delivery.py,sha256=z_cl6YKwnduGjGaB8ZoUpKhFcEAhUZqqBma8v2FO1so,2982
 svc_infra/jobs/easy.py,sha256=eix-OxWeE3vdkY3GGNoYM0GAyOxc928SpiSzMkr9k0A,977
@@ -283,7 +292,7 @@ svc_infra/webhooks/fastapi.py,sha256=BCNvGNxukf6dC2a4i-6en-PrjBGV19YvCWOot5lXWsA
 svc_infra/webhooks/router.py,sha256=6JvAVPMEth_xxHX-IsIOcyMgHX7g1H0OVxVXKLuMp9w,1596
 svc_infra/webhooks/service.py,sha256=hWgiJRXKBwKunJOx91C7EcLUkotDtD3Xp0RT6vj2IC0,1797
 svc_infra/webhooks/signing.py,sha256=NCwdZzmravUe7HVIK_uXK0qqf12FG-_MVsgPvOw6lsM,784
-svc_infra-0.1.604.dist-info/METADATA,sha256=MWq8dgYUohrtSAQkZXS6YO0oeH29rMtGqHVlQSOtX9Q,8014
-svc_infra-0.1.604.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-svc_infra-0.1.604.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
-svc_infra-0.1.604.dist-info/RECORD,,
+svc_infra-0.1.605.dist-info/METADATA,sha256=1Ng73YrdY7IbUtBEQ4PYWf2n-0qaVnZnrio6woieZ0Q,8106
+svc_infra-0.1.605.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+svc_infra-0.1.605.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
+svc_infra-0.1.605.dist-info/RECORD,,