svc-infra 0.1.621__tar.gz → 0.1.623__tar.gz

{svc_infra-0.1.621 → svc_infra-0.1.623}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: svc-infra
-Version: 0.1.621
+Version: 0.1.623
 Summary: Infrastructure for building and deploying prod-ready services
 License: MIT
 Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic
@@ -77,7 +77,7 @@ Description-Content-Type: text/markdown
 # svc-infra
 
 [![PyPI](https://img.shields.io/pypi/v/svc-infra.svg)](https://pypi.org/project/svc-infra/)
-[![Docs](https://img.shields.io/badge/docs-reference-blue)](docs/)
+[![Docs](https://img.shields.io/badge/docs-reference-blue)](src/svc_infra/docs/)
 
 svc-infra packages the shared building blocks we use to ship production FastAPI services fast—HTTP APIs with secure auth, durable persistence, background execution, cache, observability, and webhook plumbing that all share the same batteries-included defaults.
 
@@ -85,17 +85,17 @@ svc-infra packages the shared building blocks we use to ship production FastAPI
 
 | Helper | What it covers | Guide |
 | --- | --- | --- |
-| API | FastAPI bootstrap, envelopes, middleware, docs wiring | [FastAPI guide](docs/api.md) |
-| Auth | Sessions, OAuth/OIDC, MFA, SMTP delivery | [Auth settings](docs/auth.md) |
-| Database | SQL + Mongo wiring, Alembic helpers, inbox/outbox patterns | [Database guide](docs/database.md) |
-| Jobs | JobQueue, scheduler, CLI worker | [Jobs quickstart](docs/jobs.md) |
-| Cache | cashews decorators, namespace management, TTL helpers | [Cache guide](docs/cache.md) |
-| Observability | Prometheus middleware, Grafana automation, OTEL hooks | [Observability guide](docs/observability.md) |
-| 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) |
+| API | FastAPI bootstrap, envelopes, middleware, docs wiring | [FastAPI guide](src/svc_infra/docs/api.md) |
+| Auth | Sessions, OAuth/OIDC, MFA, SMTP delivery | [Auth settings](src/svc_infra/docs/auth.md) |
+| Database | SQL + Mongo wiring, Alembic helpers, inbox/outbox patterns | [Database guide](src/svc_infra/docs/database.md) |
+| Jobs | JobQueue, scheduler, CLI worker | [Jobs quickstart](src/svc_infra/docs/jobs.md) |
+| Cache | cashews decorators, namespace management, TTL helpers | [Cache guide](src/svc_infra/docs/cache.md) |
+| Observability | Prometheus middleware, Grafana automation, OTEL hooks | [Observability guide](src/svc_infra/docs/observability.md) |
+| Ops | Probes, breaker, SLOs & dashboards | [SLOs & Ops](src/svc_infra/docs/ops.md) |
+| Webhooks | Subscription store, signing, retry worker | [Webhooks framework](src/svc_infra/docs/webhooks.md) |
+| Security | Password policy, lockout, signed cookies, headers | [Security hardening](src/svc_infra/docs/security.md) |
+| Contributing | Dev setup and quality gates | [Contributing guide](src/svc_infra/docs/contributing.md) |
+| Data Lifecycle | Fixtures, retention, erasure, backups | [Data lifecycle](src/svc_infra/docs/data-lifecycle.md) |
 
 ## Minimal FastAPI bootstrap
 
@@ -123,9 +123,9 @@ async def handle_webhook(payload = Depends(require_signature(lambda: ["current",
 - **API** – toggle logging/observability and docs exposure with `ENABLE_LOGGING`, `LOG_LEVEL`, `LOG_FORMAT`, `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS`, and `CORS_ALLOW_ORIGINS`. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】【F:src/svc_infra/api/fastapi/setup.py†L47-L88】
 - **Auth** – configure JWT secrets, SMTP, cookies, and policy using the `AUTH_…` settings family (e.g., `AUTH_JWT__SECRET`, `AUTH_SMTP_HOST`, `AUTH_SESSION_COOKIE_SECURE`). 【F:src/svc_infra/api/fastapi/auth/settings.py†L23-L91】
 - **Database** – set connection URLs or components via `SQL_URL`/`SQL_URL_FILE`, `DB_DIALECT`, `DB_HOST`, `DB_USER`, `DB_PASSWORD`, plus Mongo knobs like `MONGO_URL`, `MONGO_DB`, and `MONGO_URL_FILE`. 【F:src/svc_infra/api/fastapi/db/sql/add.py†L55-L114】【F:src/svc_infra/db/sql/utils.py†L85-L206】【F:src/svc_infra/db/nosql/mongo/settings.py†L9-L13】【F:src/svc_infra/db/nosql/utils.py†L56-L113】
-- **Jobs** – choose the queue backend with `JOBS_DRIVER` and provide Redis via `REDIS_URL`; interval schedules can be declared with `JOBS_SCHEDULE_JSON`. 【F:src/svc_infra/jobs/easy.py†L11-L27】【F:docs/jobs.md†L11-L48】
+- **Jobs** – choose the queue backend with `JOBS_DRIVER` and provide Redis via `REDIS_URL`; interval schedules can be declared with `JOBS_SCHEDULE_JSON`. 【F:src/svc_infra/jobs/easy.py†L11-L27】【F:src/svc_infra/docs/jobs.md†L11-L48】
 - **Cache** – namespace keys and lifetimes through `CACHE_PREFIX`, `CACHE_VERSION`, and TTL overrides `CACHE_TTL_DEFAULT`, `CACHE_TTL_SHORT`, `CACHE_TTL_LONG`. 【F:src/svc_infra/cache/README.md†L20-L173】【F:src/svc_infra/cache/ttl.py†L26-L55】
 - **Observability** – turn metrics on/off or adjust scrape paths with `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS`, and Prometheus/Grafana flags like `SVC_INFRA_DISABLE_PROMETHEUS`, `SVC_INFRA_RATE_WINDOW`, `SVC_INFRA_DASHBOARD_REFRESH`, `SVC_INFRA_DASHBOARD_RANGE`. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】【F:src/svc_infra/obs/metrics/asgi.py†L49-L206】【F:src/svc_infra/obs/cloud_dash.py†L85-L108】
-- **Webhooks** – reuse the jobs envs (`JOBS_DRIVER`, `REDIS_URL`) for the delivery worker and queue configuration. 【F:docs/webhooks.md†L32-L53】
-- **Security** – enforce password policy, MFA, and rotation with auth prefixes such as `AUTH_PASSWORD_MIN_LENGTH`, `AUTH_PASSWORD_REQUIRE_SYMBOL`, `AUTH_JWT__SECRET`, and `AUTH_JWT__OLD_SECRETS`. 【F:docs/security.md†L24-L70】
+- **Webhooks** – reuse the jobs envs (`JOBS_DRIVER`, `REDIS_URL`) for the delivery worker and queue configuration. 【F:src/svc_infra/docs/webhooks.md†L32-L53】
+- **Security** – enforce password policy, MFA, and rotation with auth prefixes such as `AUTH_PASSWORD_MIN_LENGTH`, `AUTH_PASSWORD_REQUIRE_SYMBOL`, `AUTH_JWT__SECRET`, and `AUTH_JWT__OLD_SECRETS`. 【F:src/svc_infra/docs/security.md†L24-L70】
 

{svc_infra-0.1.621 → svc_infra-0.1.623}/README.md

@@ -1,7 +1,7 @@
 # svc-infra
 
 [![PyPI](https://img.shields.io/pypi/v/svc-infra.svg)](https://pypi.org/project/svc-infra/)
-[![Docs](https://img.shields.io/badge/docs-reference-blue)](docs/)
+[![Docs](https://img.shields.io/badge/docs-reference-blue)](src/svc_infra/docs/)
 
 svc-infra packages the shared building blocks we use to ship production FastAPI services fast—HTTP APIs with secure auth, durable persistence, background execution, cache, observability, and webhook plumbing that all share the same batteries-included defaults.
 
@@ -9,17 +9,17 @@ svc-infra packages the shared building blocks we use to ship production FastAPI
 
 | Helper | What it covers | Guide |
 | --- | --- | --- |
-| API | FastAPI bootstrap, envelopes, middleware, docs wiring | [FastAPI guide](docs/api.md) |
-| Auth | Sessions, OAuth/OIDC, MFA, SMTP delivery | [Auth settings](docs/auth.md) |
-| Database | SQL + Mongo wiring, Alembic helpers, inbox/outbox patterns | [Database guide](docs/database.md) |
-| Jobs | JobQueue, scheduler, CLI worker | [Jobs quickstart](docs/jobs.md) |
-| Cache | cashews decorators, namespace management, TTL helpers | [Cache guide](docs/cache.md) |
-| Observability | Prometheus middleware, Grafana automation, OTEL hooks | [Observability guide](docs/observability.md) |
-| 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) |
+| API | FastAPI bootstrap, envelopes, middleware, docs wiring | [FastAPI guide](src/svc_infra/docs/api.md) |
+| Auth | Sessions, OAuth/OIDC, MFA, SMTP delivery | [Auth settings](src/svc_infra/docs/auth.md) |
+| Database | SQL + Mongo wiring, Alembic helpers, inbox/outbox patterns | [Database guide](src/svc_infra/docs/database.md) |
+| Jobs | JobQueue, scheduler, CLI worker | [Jobs quickstart](src/svc_infra/docs/jobs.md) |
+| Cache | cashews decorators, namespace management, TTL helpers | [Cache guide](src/svc_infra/docs/cache.md) |
+| Observability | Prometheus middleware, Grafana automation, OTEL hooks | [Observability guide](src/svc_infra/docs/observability.md) |
+| Ops | Probes, breaker, SLOs & dashboards | [SLOs & Ops](src/svc_infra/docs/ops.md) |
+| Webhooks | Subscription store, signing, retry worker | [Webhooks framework](src/svc_infra/docs/webhooks.md) |
+| Security | Password policy, lockout, signed cookies, headers | [Security hardening](src/svc_infra/docs/security.md) |
+| Contributing | Dev setup and quality gates | [Contributing guide](src/svc_infra/docs/contributing.md) |
+| Data Lifecycle | Fixtures, retention, erasure, backups | [Data lifecycle](src/svc_infra/docs/data-lifecycle.md) |
 
 ## Minimal FastAPI bootstrap
 
@@ -47,8 +47,8 @@ async def handle_webhook(payload = Depends(require_signature(lambda: ["current",
 - **API** – toggle logging/observability and docs exposure with `ENABLE_LOGGING`, `LOG_LEVEL`, `LOG_FORMAT`, `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS`, and `CORS_ALLOW_ORIGINS`. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】【F:src/svc_infra/api/fastapi/setup.py†L47-L88】
 - **Auth** – configure JWT secrets, SMTP, cookies, and policy using the `AUTH_…` settings family (e.g., `AUTH_JWT__SECRET`, `AUTH_SMTP_HOST`, `AUTH_SESSION_COOKIE_SECURE`). 【F:src/svc_infra/api/fastapi/auth/settings.py†L23-L91】
 - **Database** – set connection URLs or components via `SQL_URL`/`SQL_URL_FILE`, `DB_DIALECT`, `DB_HOST`, `DB_USER`, `DB_PASSWORD`, plus Mongo knobs like `MONGO_URL`, `MONGO_DB`, and `MONGO_URL_FILE`. 【F:src/svc_infra/api/fastapi/db/sql/add.py†L55-L114】【F:src/svc_infra/db/sql/utils.py†L85-L206】【F:src/svc_infra/db/nosql/mongo/settings.py†L9-L13】【F:src/svc_infra/db/nosql/utils.py†L56-L113】
-- **Jobs** – choose the queue backend with `JOBS_DRIVER` and provide Redis via `REDIS_URL`; interval schedules can be declared with `JOBS_SCHEDULE_JSON`. 【F:src/svc_infra/jobs/easy.py†L11-L27】【F:docs/jobs.md†L11-L48】
+- **Jobs** – choose the queue backend with `JOBS_DRIVER` and provide Redis via `REDIS_URL`; interval schedules can be declared with `JOBS_SCHEDULE_JSON`. 【F:src/svc_infra/jobs/easy.py†L11-L27】【F:src/svc_infra/docs/jobs.md†L11-L48】
 - **Cache** – namespace keys and lifetimes through `CACHE_PREFIX`, `CACHE_VERSION`, and TTL overrides `CACHE_TTL_DEFAULT`, `CACHE_TTL_SHORT`, `CACHE_TTL_LONG`. 【F:src/svc_infra/cache/README.md†L20-L173】【F:src/svc_infra/cache/ttl.py†L26-L55】
 - **Observability** – turn metrics on/off or adjust scrape paths with `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS`, and Prometheus/Grafana flags like `SVC_INFRA_DISABLE_PROMETHEUS`, `SVC_INFRA_RATE_WINDOW`, `SVC_INFRA_DASHBOARD_REFRESH`, `SVC_INFRA_DASHBOARD_RANGE`. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】【F:src/svc_infra/obs/metrics/asgi.py†L49-L206】【F:src/svc_infra/obs/cloud_dash.py†L85-L108】
-- **Webhooks** – reuse the jobs envs (`JOBS_DRIVER`, `REDIS_URL`) for the delivery worker and queue configuration. 【F:docs/webhooks.md†L32-L53】
-- **Security** – enforce password policy, MFA, and rotation with auth prefixes such as `AUTH_PASSWORD_MIN_LENGTH`, `AUTH_PASSWORD_REQUIRE_SYMBOL`, `AUTH_JWT__SECRET`, and `AUTH_JWT__OLD_SECRETS`. 【F:docs/security.md†L24-L70】
+- **Webhooks** – reuse the jobs envs (`JOBS_DRIVER`, `REDIS_URL`) for the delivery worker and queue configuration. 【F:src/svc_infra/docs/webhooks.md†L32-L53】
+- **Security** – enforce password policy, MFA, and rotation with auth prefixes such as `AUTH_PASSWORD_MIN_LENGTH`, `AUTH_PASSWORD_REQUIRE_SYMBOL`, `AUTH_JWT__SECRET`, and `AUTH_JWT__OLD_SECRETS`. 【F:src/svc_infra/docs/security.md†L24-L70】

{svc_infra-0.1.621 → svc_infra-0.1.623}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "svc-infra"
-version = "0.1.621"
+version = "0.1.623"
 description = "Infrastructure for building and deploying prod-ready services"
 authors = ["Ali Khatami <aliikhatami94@gmail.com>"]
 license = "MIT"
@@ -13,7 +13,7 @@ include = [
     "src/svc_infra/obs/templates/**/*",
     "src/svc_infra/obs/grafana/templates/**/*",
     "src/svc_infra/obs/grafana/dashboards/**/*",
-    "docs/**/*"
+    "src/svc_infra/docs/**/*"
 ]
 
 classifiers = [

svc_infra-0.1.623/src/svc_infra/cli/cmds/docs/docs_cmds.py

@@ -0,0 +1,189 @@
+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) --docs-dir CLI option
+      2) SVC_INFRA_DOCS_DIR env var
+      3) *Only when working inside the svc-infra repo itself*: repo-root /docs
+    """
+    # 1) CLI option on this or parent contexts
+    current: click.Context | None = ctx
+    while current is not None:
+        docs_dir_opt = (current.params or {}).get("docs_dir")
+        if docs_dir_opt:
+            path = docs_dir_opt if isinstance(docs_dir_opt, Path) else Path(docs_dir_opt)
+            path = path.expanduser()
+            if path.exists():
+                return path
+        current = current.parent
+
+    # 2) Env var
+    env_dir = os.getenv("SVC_INFRA_DOCS_DIR")
+    if env_dir:
+        p = Path(env_dir).expanduser()
+        if p.exists():
+            return p
+
+    # 3) 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(
+        docs_dir: Path | None = typer.Option(
+            None,
+            "--docs-dir",
+            help="Path to a docs directory to read from (overrides packaged docs)",
+        ),
+        topic: str | None = typer.Option(None, "--topic", help="Topic to show directly"),
+    ) -> None:
+        if topic:
+            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"))
+                raise typer.Exit(code=0)
+            pkg = _discover_pkg_topics()
+            if key in pkg:
+                typer.echo(pkg[key].read_text(encoding="utf-8", errors="replace"))
+                raise typer.Exit(code=0)
+            raise typer.BadParameter(f"Unknown topic: {topic}")
+
+    @docs_app.command("list", help="List available documentation topics")
+    def list_topics() -> None:
+        ctx = click.get_current_context()
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+        pkg = _discover_pkg_topics()
+
+        def _print(name: str, path: Path) -> None:
+            try:
+                typer.echo(f"{name}\t{path}")
+            except Exception:
+                typer.echo(name)
+
+        for name, path in fs.items():
+            _print(name, path)
+        for name, path in pkg.items():
+            if name not in fs:
+                _print(name, path)
+
+    @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-0.1.621/src/svc_infra/cli/cmds/docs/docs_cmds.py

@@ -1,266 +0,0 @@
-from __future__ import annotations
-
-import importlib.util
-import os
-import sys
-from importlib.metadata import PackageNotFoundError, distribution
-from pathlib import Path
-from typing import Dict, List
-
-import click
-import typer
-from typer.core import TyperGroup
-
-
-def _norm(name: str) -> str:
-    """Normalize a topic name for stable CLI commands.
-
-    - Lowercase
-    - Replace spaces and underscores with hyphens
-    - Strip leading/trailing whitespace
-    """
-    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 packaged under 'docs/' in the installed distribution.
-
-    Works in external projects without a local docs/ by inspecting the wheel
-    metadata and, as a fallback, searching for a top-level docs/ next to the
-    installed package directory in site-packages.
-    """
-    topics: Dict[str, Path] = {}
-
-    # 1) Prefer distribution metadata (RECORD) for both hyphen/underscore names
-    dist = None
-    for name in ("svc-infra", "svc_infra"):
-        try:
-            dist = distribution(name)
-            break
-        except PackageNotFoundError:
-            dist = None
-
-    if dist is not None:
-        files = getattr(dist, "files", None) or []
-        for f in files:
-            s = str(f)
-            if not s.startswith("docs/") or not s.endswith(".md"):
-                continue
-            topic_name = _norm(Path(s).stem)
-            try:
-                abs_path = Path(dist.locate_file(f))
-                if abs_path.exists() and abs_path.is_file():
-                    topics[topic_name] = abs_path
-            except Exception:
-                # Best effort; continue to next
-                continue
-
-    # 2) Fallback: site-packages sibling 'docs/' directory (and repo-root docs in editable installs)
-    try:
-        spec = importlib.util.find_spec("svc_infra")
-        if spec and spec.submodule_search_locations:
-            pkg_dir = Path(next(iter(spec.submodule_search_locations)))
-            candidates = [
-                pkg_dir.parent / "docs",  # site-packages/docs OR src/docs
-                pkg_dir / "docs",  # site-packages/svc_infra/docs OR src/svc_infra/docs
-                pkg_dir.parent.parent
-                / "docs",  # repo-root/docs when running editable from repo (src/svc_infra → ../../docs)
-            ]
-            for candidate in candidates:
-                if candidate.exists() and candidate.is_dir():
-                    for p in sorted(candidate.glob("*.md")):
-                        if p.is_file():
-                            topics.setdefault(_norm(p.stem), p)
-                    # If one candidate had docs, that's sufficient
-                    if any(k for k in topics):
-                        break
-    except Exception:
-        # Optional fallback only
-        pass
-
-    # 3) Last-resort: scan sys.path entries that look like site-/dist-packages for a top-level docs/
-    #    directory containing markdown files. This covers non-standard installs/editable modes.
-    try:
-        if not topics:
-            for entry in sys.path:
-                try:
-                    if not entry or ("site-packages" not in entry and "dist-packages" not in entry):
-                        continue
-                    docs_dir = Path(entry) / "docs"
-                    if docs_dir.exists() and docs_dir.is_dir():
-                        found = _discover_fs_topics(docs_dir)
-                        if found:
-                            # Merge but do not override anything already found
-                            for k, v in found.items():
-                                topics.setdefault(k, v)
-                            # If we found one valid docs dir, it's enough
-                            break
-                except Exception:
-                    continue
-    except Exception:
-        pass
-
-    # 4) Parse dist-info/RECORD or egg-info/SOURCES.txt to enumerate docs if available
-    try:
-        if not topics:
-            spec = importlib.util.find_spec("svc_infra")
-            base_dir: Path | None = None
-            if spec and spec.submodule_search_locations:
-                base_dir = Path(next(iter(spec.submodule_search_locations))).parent
-            # Fallback to first site-packages on sys.path
-            if base_dir is None:
-                for entry in sys.path:
-                    if entry and "site-packages" in entry:
-                        base_dir = Path(entry)
-                        break
-            if base_dir and base_dir.exists():
-                # Check for both hyphen and underscore dist-info names
-                candidates = list(base_dir.glob("svc_infra-*.dist-info")) + list(
-                    base_dir.glob("svc-infra-*.dist-info")
-                )
-                for di in candidates:
-                    record = di / "RECORD"
-                    if record.exists():
-                        try:
-                            for line in record.read_text(
-                                encoding="utf-8", errors="ignore"
-                            ).splitlines():
-                                rel = line.split(",", 1)[0]
-                                if rel.startswith("docs/") and rel.endswith(".md"):
-                                    abs_p = base_dir / rel
-                                    if abs_p.exists() and abs_p.is_file():
-                                        topics.setdefault(_norm(Path(rel).stem), abs_p)
-                        except Exception:
-                            continue
-                # egg-info fallback
-                if not topics:
-                    egg_candidates = list(base_dir.glob("svc_infra-*.egg-info")) + list(
-                        base_dir.glob("svc-infra-*.egg-info")
-                    )
-                    for ei in egg_candidates:
-                        sources = ei / "SOURCES.txt"
-                        if sources.exists():
-                            try:
-                                for rel in sources.read_text(
-                                    encoding="utf-8", errors="ignore"
-                                ).splitlines():
-                                    rel = rel.strip()
-                                    if rel.startswith("docs/") and rel.endswith(".md"):
-                                        abs_p = base_dir / rel
-                                        if abs_p.exists() and abs_p.is_file():
-                                            topics.setdefault(_norm(Path(rel).stem), abs_p)
-                            except Exception:
-                                continue
-    except Exception:
-        pass
-
-    # 5) Deep fallback: recursively search site-packages/dist-packages for any 'docs' folder
-    #    containing markdown files (limited depth to keep overhead reasonable).
-    try:
-        if not topics:
-            for entry in sys.path:
-                if not entry or ("site-packages" not in entry and "dist-packages" not in entry):
-                    continue
-                base = Path(entry)
-                if not base.exists() or not base.is_dir():
-                    continue
-                base_parts = len(base.parts)
-                for root, dirs, files in os.walk(base):
-                    root_path = Path(root)
-                    # Limit search depth to avoid expensive scans
-                    if len(root_path.parts) - base_parts > 4:
-                        # prune
-                        dirs[:] = []
-                        continue
-                    if root_path.name == "docs":
-                        for p in sorted(root_path.glob("*.md")):
-                            if p.is_file():
-                                topics.setdefault(_norm(p.stem), p)
-                        # do not break; there might be multiple doc dirs
-    except Exception:
-        pass
-
-    return topics
-
-
-def _resolve_docs_dir(ctx: click.Context) -> Path | None:
-    # Deprecated: we no longer read docs from arbitrary paths or env.
-    # All docs are sourced from the packaged svc-infra distribution only.
-    return None
-
-
-class DocsGroup(TyperGroup):
-    def list_commands(self, ctx: click.Context) -> List[str]:
-        names: List[str] = list(super().list_commands(ctx) or [])
-        pkg = _discover_pkg_topics()
-        names.extend([k for k in pkg.keys()])
-        # Deduplicate and sort
-        return sorted({*names})
-
-    def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
-        # Built-ins first (e.g., list, show)
-        cmd = super().get_command(ctx, name)
-        if cmd is not None:
-            return cmd
-
-        # Packaged topics only
-        pkg = _discover_pkg_topics()
-        if name in pkg:
-            file_path = pkg[name]
-
-            @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:
-    """Register the `docs` command group with dynamic topic subcommands."""
-
-    docs_app = typer.Typer(no_args_is_help=True, add_completion=False, cls=DocsGroup)
-
-    @docs_app.callback(invoke_without_command=True)
-    def _docs_options(
-        topic: str | None = typer.Option(None, "--topic", help="Topic to show directly"),
-    ) -> None:
-        """Support --topic at group level (packaged docs only)."""
-        if topic:
-            pkg = _discover_pkg_topics()
-            if topic in pkg:
-                typer.echo(pkg[topic].read_text(encoding="utf-8", errors="replace"))
-                raise typer.Exit(code=0)
-            raise typer.BadParameter(f"Unknown topic: {topic}")
-
-    @docs_app.command("list", help="List available documentation topics")
-    def list_topics() -> None:
-        pkg = _discover_pkg_topics()
-
-        # Print packaged topics only
-        def _print(name: str, path: Path) -> None:
-            typer.echo(f"{name}\t{path}")
-
-        for name, path in pkg.items():
-            _print(name, path)
-
-    # Also support a generic "show" command
-    @docs_app.command("show", help="Show docs for a topic (alternative to dynamic subcommand)")
-    def show(topic: str) -> None:
-        pkg = _discover_pkg_topics()
-        if topic in pkg:
-            typer.echo(pkg[topic].read_text(encoding="utf-8", errors="replace"))
-            return
-        raise typer.BadParameter(f"Unknown topic: {topic}")
-
-    app.add_typer(docs_app, name="docs")