svc-infra 0.1.506__py3-none-any.whl → 0.1.654__py3-none-any.whl

svc_infra/cli/__init__.py

@@ -4,10 +4,15 @@ import typer
 
 from svc_infra.cli.cmds import (
     _HELP,
+    jobs_app,
     register_alembic,
+    register_docs,
+    register_dx,
     register_mongo,
     register_mongo_scaffold,
     register_obs,
+    register_sdk,
+    register_sql_export,
     register_sql_scaffold,
 )
 from svc_infra.cli.foundation.typer_bootstrap import pre_cli
@@ -15,16 +20,35 @@ from svc_infra.cli.foundation.typer_bootstrap import pre_cli
 app = typer.Typer(no_args_is_help=True, add_completion=False, help=_HELP)
 pre_cli(app)
 
-# --- sql commands ---
-register_alembic(app)
-register_sql_scaffold(app)
+# --- sql group ---
+sql_app = typer.Typer(no_args_is_help=True, add_completion=False, help="SQL commands")
+register_alembic(sql_app)
+register_sql_scaffold(sql_app)
+register_sql_export(sql_app)
+app.add_typer(sql_app, name="sql")
 
-# --- nosql commands ---
-register_mongo(app)
-register_mongo_scaffold(app)
+# --- mongo group ---
+mongo_app = typer.Typer(no_args_is_help=True, add_completion=False, help="MongoDB commands")
+register_mongo(mongo_app)
+register_mongo_scaffold(mongo_app)
+app.add_typer(mongo_app, name="mongo")
 
-# -- observability commands ---
-register_obs(app)
+# -- obs group ---
+obs_app = typer.Typer(no_args_is_help=True, add_completion=False, help="Observability commands")
+register_obs(obs_app)
+app.add_typer(obs_app, name="obs")
+
+# -- dx commands ---
+register_dx(app)
+
+# -- jobs commands ---
+app.add_typer(jobs_app, name="jobs")
+
+# -- sdk commands ---
+register_sdk(app)
+
+# -- docs commands ---
+register_docs(app)
 
 
 def main():

svc_infra/cli/__main__.py

@@ -0,0 +1,4 @@
+from . import main
+
+if __name__ == "__main__":
+    main()

svc_infra/cli/cmds/__init__.py

@@ -3,16 +3,26 @@ from svc_infra.cli.cmds.db.nosql.mongo.mongo_scaffold_cmds import (
     register as register_mongo_scaffold,
 )
 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.docs.docs_cmds import register as register_docs
+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
 
 __all__ = [
     "register_alembic",
     "register_sql_scaffold",
+    "register_sql_export",
     "register_mongo",
     "register_mongo_scaffold",
     "register_obs",
+    "jobs_app",
+    "register_sdk",
+    "register_dx",
+    "register_docs",
     "_HELP",
 ]

svc_infra/cli/cmds/db/nosql/mongo/mongo_cmds.py

@@ -188,6 +188,7 @@ def cmd_ping(
 
 
 def register(app: typer.Typer) -> None:
-    app.command("mongo-prepare")(cmd_prepare)
-    app.command("mongo-setup-and-prepare")(cmd_setup_and_prepare)
-    app.command("mongo-ping")(cmd_ping)
+    # Attach to 'mongo' group app
+    app.command("prepare")(cmd_prepare)
+    app.command("setup-and-prepare")(cmd_setup_and_prepare)
+    app.command("ping")(cmd_ping)

svc_infra/cli/cmds/db/nosql/mongo/mongo_scaffold_cmds.py

@@ -127,7 +127,7 @@ def register(app: typer.Typer) -> None:
       • mongo-scaffold-schemas
       • mongo-scaffold-resources
     """
-    app.command("mongo-scaffold")(cmd_scaffold)
-    app.command("mongo-scaffold-documents")(cmd_scaffold_documents)
-    app.command("mongo-scaffold-schemas")(cmd_scaffold_schemas)
-    app.command("mongo-scaffold-resources")(cmd_scaffold_resources)
+    app.command("scaffold")(cmd_scaffold)
+    app.command("scaffold-documents")(cmd_scaffold_documents)
+    app.command("scaffold-schemas")(cmd_scaffold_schemas)
+    app.command("scaffold-resources")(cmd_scaffold_resources)

svc_infra/cli/cmds/db/sql/alembic_cmds.py

@@ -1,10 +1,13 @@
 from __future__ import annotations
 
+import json
 import os
+from importlib import import_module
 from typing import List, Optional
 
 import typer
 
+from svc_infra.apf_payments.alembic import discover_packages as payments_pkgs
 from svc_infra.db.sql.core import current as core_current
 from svc_infra.db.sql.core import downgrade as core_downgrade
 from svc_infra.db.sql.core import history as core_history
@@ -22,6 +25,23 @@ def apply_database_url(database_url: Optional[str]) -> None:
         os.environ["SQL_URL"] = database_url
 
 
+def _find_pkgs(with_payments, discover_packages) -> List[str]:
+    from os import getenv
+
+    payments_enabled = (
+        with_payments
+        if with_payments is not None
+        else str(getenv("APF_ENABLE_PAYMENTS", "")).lower() in {"1", "true", "yes"}
+    )
+    final_pkgs = list(discover_packages or [])
+    if payments_enabled:
+        for p in payments_pkgs():
+            if p not in final_pkgs:
+                final_pkgs.append(p)
+
+    return final_pkgs
+
+
 def cmd_init(
     database_url: Optional[str] = typer.Option(
         None,
@@ -34,14 +54,20 @@ def cmd_init(
         "If omitted, automatic discovery is used.",
     ),
     overwrite: bool = typer.Option(False, help="Overwrite existing files if present."),
+    with_payments: bool = typer.Option(
+        None,
+        help="Include svc-infra payments models when rendering env.py. "
+        "Defaults from env APF_ENABLE_PAYMENTS.",
+    ),
 ):
     """
     Initialize Alembic scaffold. The env.py variant (async vs. sync) is
     auto-detected from SQL_URL (if available at init time).
     """
+    final_pkgs = _find_pkgs(with_payments, discover_packages)
     apply_database_url(database_url)
     core_init_alembic(
-        discover_packages=discover_packages,
+        discover_packages=final_pkgs or None,
         overwrite=overwrite,
     )
 
@@ -99,7 +125,11 @@ def cmd_current(
 ):
     """Display the current revision for each database."""
     apply_database_url(database_url)
-    core_current(verbose=verbose)
+    result = core_current(verbose=verbose)
+    try:
+        typer.echo(json.dumps(result))
+    except Exception:
+        typer.echo(str(result))
 
 
 def cmd_history(
@@ -147,28 +177,104 @@ def cmd_setup_and_migrate(
     ),
     initial_message: str = typer.Option("initial schema"),
     followup_message: str = typer.Option("autogen"),
+    # NEW:
+    discover_packages: Optional[List[str]] = typer.Option(
+        None,
+        help="Packages Alembic should import to discover models "
+        "(e.g. app.models,svc_infra.apf_payments.models).",
+    ),
+    with_payments: bool = typer.Option(
+        None,  # None = read env
+        help="Include svc-infra payments models in migrations. "
+        "If omitted, falls back to env APF_ENABLE_PAYMENTS=true/1.",
+    ),
 ):
     """
-    End-to-end: ensure DB exists, scaffold Alembic, create/upgrade revisions.
+    End-to-end: ensure DB exists, scaffold Alembic, create/upgrade, all in one command.
     Async vs. sync is inferred from SQL_URL.
     """
-    apply_database_url(database_url)
-    core_setup_and_migrate(
+    final_pkgs = _find_pkgs(with_payments, discover_packages)
+    result = core_setup_and_migrate(
         overwrite_scaffold=overwrite_scaffold,
         create_db_if_missing=create_db_if_missing,
         create_followup_revision=create_followup_revision,
         initial_message=initial_message,
         followup_message=followup_message,
+        discover_packages=final_pkgs or None,
+        database_url=database_url,
     )
+    # Echo a concise JSON result so tests and users can introspect outcome
+    try:
+        typer.echo(json.dumps(result))
+    except Exception:
+        # Fallback to plain string if not JSON-serializable for any reason
+        typer.echo(str(result))
 
 
 def register(app: typer.Typer) -> None:
-    app.command("sql-init")(cmd_init)
-    app.command("sql-revision")(cmd_revision)
-    app.command("sql-upgrade")(cmd_upgrade)
-    app.command("sql-downgrade")(cmd_downgrade)
-    app.command("sql-current")(cmd_current)
-    app.command("sql-history")(cmd_history)
-    app.command("sql-stamp")(cmd_stamp)
-    app.command("sql-merge-heads")(cmd_merge_heads)
-    app.command("sql-setup-and-migrate")(cmd_setup_and_migrate)
+    # Register under the 'sql' group app
+    app.command("init")(cmd_init)
+    app.command("revision")(cmd_revision)
+    app.command("upgrade")(cmd_upgrade)
+    # Allow unknown options so users can pass "-1" like Alembic without Click treating it as an option
+    app.command(
+        "downgrade",
+        context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+    )(cmd_downgrade)
+    app.command("current")(cmd_current)
+    app.command("history")(cmd_history)
+    app.command("stamp")(cmd_stamp)
+    app.command("merge-heads")(cmd_merge_heads)
+    app.command("setup-and-migrate")(cmd_setup_and_migrate)
+    app.command("seed")(cmd_seed)
+
+
+def _import_callable(path: str):
+    mod_name, _, fn_name = path.partition(":")
+    if not mod_name or not fn_name:
+        raise typer.BadParameter("Expected format 'module.path:callable'")
+    # Back-compat: after moving tests under tests/unit, allow legacy test module
+    # dotted paths like 'tests.db.sql.test_sql_seed_cli:my_seed'.
+    mod = None
+    unit_mod = None
+    if mod_name.startswith("tests.db."):
+        # Try legacy import first (shim module), then unit module fallback
+        try:
+            mod = import_module(mod_name)
+        except ModuleNotFoundError:
+            pass
+        unit_name = mod_name.replace("tests.db.", "tests.unit.db.", 1)
+        try:
+            unit_mod = import_module(unit_name)
+        except ModuleNotFoundError:
+            unit_mod = None
+        # If both exist, unify shared state where applicable
+        if mod is not None and unit_mod is not None:
+            # Example: tests use a global `called` dict; point legacy to unit
+            try:
+                if hasattr(unit_mod, "called"):
+                    setattr(mod, "called", getattr(unit_mod, "called"))
+            except Exception:
+                pass
+        # If legacy mod missing but unit exists, use unit
+        if mod is None and unit_mod is not None:
+            mod = unit_mod
+    else:
+        mod = import_module(mod_name)
+    fn = getattr(mod, fn_name, None)
+    if not callable(fn):
+        raise typer.BadParameter(f"Callable '{fn_name}' not found in module '{mod_name}'")
+    return fn
+
+
+def cmd_seed(
+    target: str = typer.Argument(..., help="Seed callable path 'module:func'"),
+    database_url: Optional[str] = typer.Option(
+        None,
+        help="Database URL; overrides env for this command.",
+    ),
+):
+    """Run a user-provided seed function to load fixtures/reference data."""
+    apply_database_url(database_url)
+    fn = _import_callable(target)
+    fn()

svc_infra/cli/cmds/db/sql/sql_export_cmds.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+from sqlalchemy import text
+
+from svc_infra.db.sql.utils import build_engine
+
+try:  # SQLAlchemy async extras are optional
+    from sqlalchemy.ext.asyncio import AsyncEngine
+except Exception:  # pragma: no cover - fallback when async extras unavailable
+    AsyncEngine = None  # type: ignore[assignment]
+
+
+def export_tenant(
+    table: str = typer.Argument(..., help="Qualified table name to export (e.g., public.items)"),
+    tenant_id: str = typer.Option(..., "--tenant-id", help="Tenant id value to filter by."),
+    tenant_field: str = typer.Option("tenant_id", help="Column name for tenant id filter."),
+    output: Optional[Path] = typer.Option(
+        None, "--output", help="Output file; defaults to stdout."
+    ),
+    limit: Optional[int] = typer.Option(None, help="Max rows to export."),
+    database_url: Optional[str] = typer.Option(
+        None, "--database-url", help="Overrides env SQL_URL for this command."
+    ),
+):
+    """Export rows for a tenant from a given SQL table as JSON array."""
+    if database_url:
+        os.environ["SQL_URL"] = database_url
+
+    url = os.getenv("SQL_URL")
+    if not url:
+        typer.echo("SQL_URL is required (or pass --database-url)", err=True)
+        raise typer.Exit(code=2)
+
+    engine = build_engine(url)
+    rows: list[dict[str, Any]]
+    query = f"SELECT * FROM {table} WHERE {tenant_field} = :tenant_id"
+    if limit and limit > 0:
+        query += " LIMIT :limit"
+
+    params: dict[str, Any] = {"tenant_id": tenant_id}
+    if limit and limit > 0:
+        params["limit"] = int(limit)
+
+    stmt = text(query)
+
+    is_async_engine = AsyncEngine is not None and isinstance(engine, AsyncEngine)
+
+    if is_async_engine:
+        assert AsyncEngine is not None  # for type checkers
+
+        async def _fetch() -> list[dict[str, Any]]:
+            async with engine.connect() as conn:  # type: ignore[call-arg]
+                result = await conn.execute(stmt, params)
+                return [dict(row) for row in result.mappings()]
+
+        rows = asyncio.run(_fetch())
+    else:
+        with engine.connect() as conn:  # type: ignore[attr-defined]
+            result = conn.execute(stmt, params)
+            rows = [dict(row) for row in result.mappings()]
+
+    data = json.dumps(rows, indent=2)
+    if output:
+        output.write_text(data)
+        typer.echo(str(output))
+    else:
+        sys.stdout.write(data)
+
+
+def register(app_root: typer.Typer) -> None:
+    # Attach directly to the provided 'sql' group app
+    app_root.command("export-tenant")(export_tenant)

svc_infra/cli/cmds/db/sql/sql_scaffold_cmds.py

@@ -24,7 +24,8 @@ def cmd_scaffold(
         "Item", help="Class name for entity/auth (e.g., User, Member, Product)."
     ),
     table_name: Optional[str] = typer.Option(
-        None, help="Optional table name (defaults to plural snake of entity name)."
+        None,
+        help="Optional table name. For kind=auth, can also be set via AUTH_TABLE_NAME; defaults to plural snake of entity.",
     ),
     models_dir: Path = typer.Option(..., help="Directory for models."),
     schemas_dir: Path = typer.Option(..., help="Directory for schemas."),
@@ -133,6 +134,6 @@ def cmd_scaffold_schemas(
 
 
 def register(app: typer.Typer) -> None:
-    app.command("sql-scaffold")(cmd_scaffold)
-    app.command("sql-scaffold-models")(cmd_scaffold_models)
-    app.command("sql-scaffold-schemas")(cmd_scaffold_schemas)
+    app.command("scaffold")(cmd_scaffold)
+    app.command("scaffold-models")(cmd_scaffold_models)
+    app.command("scaffold-schemas")(cmd_scaffold_schemas)

svc_infra/cli/cmds/docs/docs_cmds.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import os
+from importlib.resources import as_file
+from importlib.resources import files as pkg_files
+from pathlib import Path
+from typing import Dict, List
+
+import click
+import typer
+from typer.core import TyperGroup
+
+from svc_infra.app.root import resolve_project_root
+
+
+def _norm(name: str) -> str:
+    return name.strip().lower().replace(" ", "-").replace("_", "-")
+
+
+def _discover_fs_topics(docs_dir: Path) -> Dict[str, Path]:
+    topics: Dict[str, Path] = {}
+    if docs_dir.exists() and docs_dir.is_dir():
+        for p in sorted(docs_dir.glob("*.md")):
+            if p.is_file():
+                topics[_norm(p.stem)] = p
+    return topics
+
+
+def _discover_pkg_topics() -> Dict[str, Path]:
+    """
+    Discover docs shipped inside the installed package at svc_infra/docs/*,
+    using importlib.resources so this works for wheels, sdists, and zipped wheels.
+    """
+    topics: Dict[str, Path] = {}
+    try:
+        docs_root = pkg_files("svc_infra").joinpath("docs")
+        # docs_root is a Traversable; it may be inside a zip. Iterate safely.
+        for entry in docs_root.iterdir():
+            if entry.name.endswith(".md"):
+                # materialize to a real tempfile path if needed
+                with as_file(entry) as concrete:
+                    p = Path(concrete)
+                    if p.exists() and p.is_file():
+                        topics[_norm(p.stem)] = p
+    except Exception:
+        # If the package has no docs directory, just return empty.
+        pass
+    return topics
+
+
+def _resolve_docs_dir(ctx: click.Context) -> Path | None:
+    """
+    Optional override precedence:
+      1) SVC_INFRA_DOCS_DIR env var
+      2) *Only when working inside the svc-infra repo itself*: repo-root /docs
+    """
+    # 1) Env var
+    env_dir = os.getenv("SVC_INFRA_DOCS_DIR")
+    if env_dir:
+        p = Path(env_dir).expanduser()
+        if p.exists():
+            return p
+
+    # 2) In-repo convenience (so `svc-infra docs` works inside this repo)
+    try:
+        root = resolve_project_root()
+        proj_docs = root / "docs"
+        if proj_docs.exists():
+            return proj_docs
+    except Exception:
+        pass
+
+    return None
+
+
+class DocsGroup(TyperGroup):
+    def list_commands(self, ctx: click.Context) -> List[str]:
+        names: List[str] = list(super().list_commands(ctx) or [])
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+        pkg = _discover_pkg_topics()
+        names.extend(fs.keys())
+        names.extend([k for k in pkg.keys() if k not in fs])
+        return sorted(set(names))
+
+    def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
+        cmd = super().get_command(ctx, name)
+        if cmd is not None:
+            return cmd
+
+        key = _norm(name)
+
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+        if key in fs:
+            file_path = fs[key]
+
+            @click.command(name=name)
+            def _show_fs() -> None:
+                click.echo(file_path.read_text(encoding="utf-8", errors="replace"))
+
+            return _show_fs
+
+        pkg = _discover_pkg_topics()
+        if key in pkg:
+            file_path = pkg[key]
+
+            @click.command(name=name)
+            def _show_pkg() -> None:
+                click.echo(file_path.read_text(encoding="utf-8", errors="replace"))
+
+            return _show_pkg
+
+        return None
+
+
+def register(app: typer.Typer) -> None:
+    docs_app = typer.Typer(no_args_is_help=True, add_completion=False, cls=DocsGroup)
+
+    @docs_app.callback(invoke_without_command=True)
+    def _docs_options() -> None:
+        # No group-level options; dynamic commands and 'show' handle topics.
+        return None
+
+    @docs_app.command("show", help="Show docs for a topic (alternative to dynamic subcommand)")
+    def show(topic: str) -> None:
+        key = _norm(topic)
+        ctx = click.get_current_context()
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+        if key in fs:
+            typer.echo(fs[key].read_text(encoding="utf-8", errors="replace"))
+            return
+        pkg = _discover_pkg_topics()
+        if key in pkg:
+            typer.echo(pkg[key].read_text(encoding="utf-8", errors="replace"))
+            return
+        raise typer.BadParameter(f"Unknown topic: {topic}")
+
+    app.add_typer(docs_app, name="docs")

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/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