svc-infra 0.1.589__py3-none-any.whl → 0.1.706__py3-none-any.whl

svc_infra/cli/cmds/dx/dx_cmds.py

@@ -0,0 +1,116 @@
+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/health/__init__.py

@@ -0,0 +1,179 @@
+"""Health check CLI commands.
+
+Provides CLI commands for health checking:
+- check: Check health of a URL endpoint
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import typer
+
+
+def cmd_check(
+    url: str = typer.Argument(
+        ...,
+        help="URL of the health endpoint to check.",
+    ),
+    timeout: float = typer.Option(
+        10.0,
+        "--timeout",
+        "-t",
+        help="Request timeout in seconds.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Output as JSON.",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show detailed response.",
+    ),
+) -> None:
+    """
+    Check health of a URL endpoint.
+
+    Fetches the URL and reports the health status based on HTTP response.
+    Expects the endpoint to return 200 for healthy status.
+
+    Examples:
+        svc-infra health check http://localhost:8000/health
+        svc-infra health check http://api:8080/ready --timeout 5
+        svc-infra health check http://localhost:8000/health --json
+
+    Exit codes:
+        0: Healthy (HTTP 2xx)
+        1: Unhealthy or unreachable
+    """
+
+    async def _check() -> dict:
+        """Perform the health check and return result."""
+        from svc_infra.health import check_url
+
+        # Create the check function with the given URL
+        check_fn = check_url(url, timeout=timeout)
+
+        # Run the check
+        result = await check_fn()
+
+        return result.to_dict()
+
+    result = asyncio.run(_check())
+
+    if json_output:
+        typer.echo(json.dumps(result, indent=2))
+    else:
+        status = result["status"]
+        latency = result["latency_ms"]
+
+        if status == "healthy":
+            typer.secho(f"✓ {url}", fg=typer.colors.GREEN)
+            typer.echo(f"  Status: {status} ({latency:.1f}ms)")
+        else:
+            typer.secho(f"✗ {url}", fg=typer.colors.RED)
+            typer.echo(f"  Status: {status}")
+            if result.get("message"):
+                typer.echo(f"  Message: {result['message']}")
+
+        if verbose and result.get("details"):
+            typer.echo("  Details:")
+            for key, value in result["details"].items():
+                typer.echo(f"    {key}: {value}")
+
+    # Exit with error code if unhealthy
+    if result["status"] != "healthy":
+        raise typer.Exit(1)
+
+
+def cmd_wait(
+    url: str = typer.Argument(
+        ...,
+        help="URL of the health endpoint to wait for.",
+    ),
+    timeout: int = typer.Option(
+        60,
+        "--timeout",
+        "-t",
+        help="Maximum time to wait in seconds.",
+    ),
+    interval: float = typer.Option(
+        2.0,
+        "--interval",
+        "-i",
+        help="Time between checks in seconds.",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Suppress progress messages.",
+    ),
+) -> None:
+    """
+    Wait for a health endpoint to become healthy.
+
+    Repeatedly checks the URL until it returns a healthy response
+    or timeout is reached.
+
+    Examples:
+        svc-infra health wait http://localhost:8000/health
+        svc-infra health wait http://api:8080/ready --timeout 120
+
+    Exit codes:
+        0: Endpoint became healthy
+        1: Timeout reached, endpoint not healthy
+    """
+    import time
+
+    async def _wait() -> bool:
+        """Wait loop."""
+        from svc_infra.health import check_url
+
+        check_fn = check_url(url, timeout=5.0)
+        deadline = time.monotonic() + timeout
+        attempt = 0
+
+        while time.monotonic() < deadline:
+            attempt += 1
+            if not quiet:
+                typer.echo(f"Attempt {attempt}: Checking {url}...")
+
+            result = await check_fn()
+
+            if result.status == "healthy":
+                if not quiet:
+                    typer.secho(
+                        f"✓ Healthy ({result.latency_ms:.1f}ms)",
+                        fg=typer.colors.GREEN,
+                    )
+                return True
+
+            if not quiet:
+                msg = result.message or "Unhealthy"
+                typer.echo(f"  → {msg}")
+
+            remaining = deadline - time.monotonic()
+            if remaining > 0:
+                await asyncio.sleep(min(interval, remaining))
+
+        return False
+
+    success = asyncio.run(_wait())
+    if not success:
+        typer.secho(
+            f"ERROR: Endpoint not healthy after {timeout}s",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1)
+
+
+def register(app: typer.Typer) -> None:
+    """Register health check commands with the CLI app."""
+    app.command("check")(cmd_check)
+    app.command("wait")(cmd_wait)

svc_infra/cli/cmds/health/health_cmds.py

@@ -0,0 +1,8 @@
+"""Health check CLI commands module.
+
+Re-exports from health/__init__.py for backward compatibility.
+"""
+
+from svc_infra.cli.cmds.health import register
+
+__all__ = ["register"]

svc_infra/cli/cmds/help.py

@@ -21,4 +21,8 @@ How to run (pick what fits your workflow):
 Notes:
 * Make sure you’re in the right virtual environment (or use `pipx`).
 * You can point `--project-root` at your Alembic root; if omitted we auto-detect.
+
+Learn more:
+* Explore available topics: `svc-infra docs --help`
+* Show a topic directly: `svc-infra docs <topic>` or `svc-infra docs show <topic>`
 """

svc_infra/cli/cmds/jobs/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

svc_infra/cli/cmds/jobs/jobs_cmds.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Optional
+
+import typer
+
+from svc_infra.jobs.easy import easy_jobs
+from svc_infra.jobs.loader import schedule_from_env
+from svc_infra.jobs.worker import process_one
+
+app = typer.Typer(help="Background jobs and scheduler commands")
+
+
+@app.command("run")
+def run(
+    poll_interval: float = typer.Option(
+        0.5, help="Sleep seconds between loops when idle"
+    ),
+    max_loops: Optional[int] = typer.Option(
+        None, help="Max loops before exit (for tests)"
+    ),
+):
+    """Run scheduler ticks and process jobs in a simple loop."""
+
+    queue, scheduler = easy_jobs()
+    # load schedule from env JSON if provided
+    schedule_from_env(scheduler)
+
+    async def _loop():
+        loops = 0
+        while True:
+            await scheduler.tick()
+            processed = await process_one(queue, _noop_handler)
+            if not processed:
+                # idle
+                await asyncio.sleep(poll_interval)
+            if max_loops is not None:
+                loops += 1
+                if loops >= max_loops:
+                    break
+
+    async def _noop_handler(job):
+        # Default handler does nothing; users should write their own runners
+        return None
+
+    asyncio.run(_loop())

svc_infra/cli/cmds/obs/obs_cmds.py

@@ -4,18 +4,22 @@ import os
 import socket
 import subprocess
 from pathlib import Path
+from typing import Any, Callable
 from urllib.parse import urlparse
 
 import typer
 
+from svc_infra.obs.cloud_dash import push_dashboards_from_pkg
+from svc_infra.utils import render_template, write
+
 # --- NEW: load .env automatically (best-effort) ---
+load_dotenv: Callable[..., Any] | None
 try:
-    from dotenv import load_dotenv  # type: ignore
+    from dotenv import load_dotenv as _real_load_dotenv
 except Exception:  # pragma: no cover
     load_dotenv = None
-
-from svc_infra.obs.cloud_dash import push_dashboards_from_pkg
-from svc_infra.utils import render_template, write
+else:
+    load_dotenv = _real_load_dotenv
 
 
 def _run(cmd: list[str], *, env: dict | None = None):
@@ -25,7 +29,9 @@ def _run(cmd: list[str], *, env: dict | None = None):
 def _emit_local_stack(root: Path, metrics_url: str):
     write(
         root / "docker-compose.yml",
-        render_template("svc_infra.obs.providers.grafana.templates", "docker-compose.yml.tmpl", {}),
+        render_template(
+            "svc_infra.obs.providers.grafana.templates", "docker-compose.yml.tmpl", {}
+        ),
     )
     p = urlparse(metrics_url)
     prom_yml = render_template(
@@ -102,7 +108,7 @@ def up():
       - Else → Local mode (Grafana + Prometheus).
     """
     # NEW: load .env once, best-effort, without crashing if package missing
-    if load_dotenv:
+    if load_dotenv is not None:
         try:
             load_dotenv(dotenv_path=Path(".env"), override=False)
         except Exception:
@@ -110,7 +116,9 @@ def up():
 
     root = Path(".obs")
     root.mkdir(exist_ok=True)
-    metrics_url = os.getenv("SVC_INFRA_METRICS_URL", "http://host.docker.internal:8000/metrics")
+    metrics_url = os.getenv(
+        "SVC_INFRA_METRICS_URL", "http://host.docker.internal:8000/metrics"
+    )
 
     cloud_url = os.getenv("GRAFANA_CLOUD_URL", "").strip()
     cloud_token = os.getenv("GRAFANA_CLOUD_TOKEN", "").strip()
@@ -131,7 +139,14 @@ def up():
         ):
             _emit_local_agent(root, metrics_url)
             _run(
-                ["docker", "compose", "-f", str(root / "docker-compose.cloud.yml"), "up", "-d"],
+                [
+                    "docker",
+                    "compose",
+                    "-f",
+                    str(root / "docker-compose.cloud.yml"),
+                    "up",
+                    "-d",
+                ],
                 env=os.environ.copy(),
             )
             typer.echo("[cloud] local Grafana Agent started (pushing metrics to Cloud)")
@@ -146,7 +161,10 @@ def up():
     env["GRAFANA_PORT"] = str(local_graf)
     env["PROM_PORT"] = str(local_prom)
     _emit_local_stack(root, metrics_url)
-    _run(["docker", "compose", "-f", str(root / "docker-compose.yml"), "up", "-d"], env=env)
+    _run(
+        ["docker", "compose", "-f", str(root / "docker-compose.yml"), "up", "-d"],
+        env=env,
+    )
     typer.echo(f"Local Grafana → http://localhost:{local_graf}  (admin/admin)")
     typer.echo(f"Local Prometheus → http://localhost:{local_prom}")
 
@@ -155,11 +173,13 @@ def down():
     root = Path(".obs")
     if (root / "docker-compose.yml").exists():
         subprocess.run(
-            ["docker", "compose", "-f", str(root / "docker-compose.yml"), "down"], check=False
+            ["docker", "compose", "-f", str(root / "docker-compose.yml"), "down"],
+            check=False,
         )
     if (root / "docker-compose.cloud.yml").exists():
         subprocess.run(
-            ["docker", "compose", "-f", str(root / "docker-compose.cloud.yml"), "down"], check=False
+            ["docker", "compose", "-f", str(root / "docker-compose.cloud.yml"), "down"],
+            check=False,
         )
     typer.echo("Stopped local obs services.")
 
@@ -171,7 +191,7 @@ def scaffold(target: str = typer.Option(..., help="compose|railway|k8s|fly")):
     out.mkdir(parents=True, exist_ok=True)
 
     base = files("svc_infra.obs.templates.sidecars").joinpath(target)
-    for p in base.rglob("*"):
+    for p in base.rglob("*"):  # type: ignore[attr-defined]
         if p.is_file():
             rel = p.relative_to(base)
             dst = out / rel
@@ -182,6 +202,7 @@ def scaffold(target: str = typer.Option(..., help="compose|railway|k8s|fly")):
 
 
 def register(app: typer.Typer) -> None:
-    app.command("obs-up")(up)
-    app.command("obs-down")(down)
-    app.command("obs-scaffold")(scaffold)
+    # Attach to 'obs' group app
+    app.command("up")(up)
+    app.command("down")(down)
+    app.command("scaffold")(scaffold)

svc_infra/cli/cmds/sdk/sdk_cmds.py

@@ -0,0 +1,112 @@
+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/cli/foundation/runner.py

@@ -25,7 +25,9 @@ def candidate_cmds(root: Path, prog: str, argv: List[str]) -> List[List[str]]:
         cmds.append([prog, *argv])
 
     py = shutil.which("python3") or shutil.which("python") or "python"
-    module = prog.replace("-", "_") + ".cli_shim"  # e.g., svc-infra -> svc_infra.cli_shim
+    module = (
+        prog.replace("-", "_") + ".cli_shim"
+    )  # e.g., svc-infra -> svc_infra.cli_shim
     cmds.append([py, "-m", module, *argv])
 
     return cmds
@@ -54,4 +56,6 @@ async def run_from_root(root: Path, prog: str, argv: List[str]) -> str:
         except Exception as e:
             last_exc = e
             continue
-    raise RuntimeError(f"All runners failed in {root} for: {prog} {' '.join(argv)}") from last_exc
+    raise RuntimeError(
+        f"All runners failed in {root} for: {prog} {' '.join(argv)}"
+    ) from last_exc

svc_infra/data/add.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import inspect
+from typing import Callable, Iterable, Optional
+
+from fastapi import FastAPI
+
+from svc_infra.cli.cmds.db.sql.alembic_cmds import cmd_setup_and_migrate
+
+
+def add_data_lifecycle(
+    app: FastAPI,
+    *,
+    auto_migrate: bool = True,
+    database_url: str | None = None,
+    discover_packages: Optional[list[str]] = None,
+    with_payments: bool | None = None,
+    on_load_fixtures: Optional[Callable[[], None]] = None,
+    retention_jobs: Optional[Iterable[Callable[[], None]]] = None,
+    erasure_job: Optional[Callable[[str], None]] = None,
+) -> None:
+    """
+    Wire data lifecycle conveniences:
+
+    - auto_migrate: run end-to-end Alembic setup-and-migrate on startup (idempotent).
+    - on_load_fixtures: optional callback to load reference/fixture data once at startup.
+    - retention_jobs: optional list of callables to register purge tasks (scheduler integration is external).
+    - erasure_job: optional callable to trigger a GDPR erasure workflow for a given principal ID.
+
+    This helper is intentionally minimal: it coordinates existing building blocks
+    and offers extension points. Jobs should be scheduled using svc_infra.jobs helpers.
+    """
+
+    async def _run_lifecycle() -> None:
+        # Startup
+        if auto_migrate:
+            cmd_setup_and_migrate(
+                database_url=database_url,
+                overwrite_scaffold=False,
+                create_db_if_missing=True,
+                create_followup_revision=True,
+                initial_message="initial schema",
+                followup_message="autogen",
+                discover_packages=discover_packages,
+                with_payments=with_payments if with_payments is not None else False,
+            )
+        if on_load_fixtures:
+            res = on_load_fixtures()
+            if inspect.isawaitable(res):
+                await res
+
+    app.add_event_handler("startup", _run_lifecycle)
+
+    # Store optional jobs on app.state for external schedulers to discover/register.
+    if retention_jobs is not None:
+        app.state.data_retention_jobs = list(retention_jobs)
+    if erasure_job is not None:
+        app.state.data_erasure_job = erasure_job
+
+
+__all__ = ["add_data_lifecycle"]