kstlib 1.0.2__py3-none-any.whl → 1.1.1__py3-none-any.whl

kstlib/cli/commands/rapi/list.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Annotated
+from typing import TYPE_CHECKING, Annotated
 
 import typer
 from rich.table import Table
@@ -10,6 +10,150 @@ from rich.table import Table
 from kstlib.cli.common import console
 from kstlib.rapi import load_rapi_config
 
+if TYPE_CHECKING:
+    from kstlib.rapi.config import ApiConfig, EndpointConfig
+
+
+def _matches_filter(
+    filter_terms: list[str],
+    ref: str,
+    method: str,
+    path: str,
+    description: str | None,
+) -> bool:
+    """Check if endpoint matches all filter terms (AND logic).
+
+    Args:
+        filter_terms: List of lowercase search terms.
+        ref: Endpoint reference (e.g., "github.repos").
+        method: HTTP method (e.g., "GET").
+        path: Endpoint path.
+        description: Optional endpoint description.
+
+    Returns:
+        True if all terms match any field.
+    """
+    searchable = f"{ref} {method} {path} {description or ''}".lower()
+    return all(term in searchable for term in filter_terms)
+
+
+def _build_query_body_display(
+    ep_config: EndpointConfig,
+    method: str,
+) -> tuple[str, str]:
+    """Build query and body column displays.
+
+    Args:
+        ep_config: Endpoint configuration.
+        method: HTTP method.
+
+    Returns:
+        Tuple of (query_display, body_display).
+    """
+    query_display = f"[yellow]{len(ep_config.query)}[/]" if ep_config.query else "-"
+    body_display = "-"
+    if ep_config.body_template and method in ("POST", "PUT", "PATCH"):
+        body_display = f"[green]{len(ep_config.body_template)}[/]"
+    return query_display, body_display
+
+
+def _build_compact_indicator(ep_config: EndpointConfig, method: str) -> str:
+    """Build compact param indicator for non-verbose mode.
+
+    Args:
+        ep_config: Endpoint configuration.
+        method: HTTP method.
+
+    Returns:
+        Formatted indicator string (e.g., " (4) (2)").
+    """
+    indicator = ""
+    if ep_config.query:
+        indicator += f" [yellow]({len(ep_config.query)})[/]"
+    if ep_config.body_template and method in ("POST", "PUT", "PATCH"):
+        indicator += f" [green]({len(ep_config.body_template)})[/]"
+    return indicator
+
+
+def _add_endpoint_row(
+    table: Table,
+    ep_config: EndpointConfig,
+    api_name: str,
+    verbose: bool,
+    *,
+    short_desc: bool = False,
+) -> None:
+    """Add a single endpoint row to the table.
+
+    Args:
+        table: Rich table to add row to.
+        ep_config: Endpoint configuration.
+        api_name: Parent API name.
+        verbose: Whether to show verbose columns.
+        short_desc: Whether to truncate description (verbose mode only).
+    """
+    ref = f"{api_name}.{ep_config.name}"
+    method = ep_config.method.upper()
+    path_display = f"[dim]{ep_config.path}[/]"
+
+    if verbose:
+        query_display, body_display = _build_query_body_display(ep_config, method)
+        description = ep_config.description or ""
+        desc_display = (description[:40] + "...") if short_desc and len(description) > 43 else description
+        table.add_row(ref, method, path_display, query_display, body_display, desc_display)
+    else:
+        indicator = _build_compact_indicator(ep_config, method)
+        table.add_row(ref, method, path_display + indicator)
+
+
+def _create_table(verbose: bool) -> Table:
+    """Create the endpoints table with appropriate columns.
+
+    Args:
+        verbose: Whether to include verbose columns.
+
+    Returns:
+        Configured Rich table.
+    """
+    table = Table(title="Available Endpoints", show_lines=False)
+    table.add_column("Reference", style="cyan")
+    table.add_column("Method", style="green", justify="center")
+    table.add_column("Path")
+
+    if verbose:
+        table.add_column("Query", justify="center")
+        table.add_column("Body", justify="center")
+        table.add_column("Description", style="dim")
+
+    return table
+
+
+def _collect_matching_endpoints(
+    apis: dict[str, ApiConfig],
+    filter_terms: list[str],
+) -> list[tuple[str, EndpointConfig]]:
+    """Collect endpoints matching the filter.
+
+    Args:
+        apis: Dictionary of API configurations.
+        filter_terms: List of lowercase filter terms.
+
+    Returns:
+        List of (api_name, endpoint_config) tuples.
+    """
+    results = []
+    for api_name, api_config in sorted(apis.items()):
+        for ep_name, ep_config in sorted(api_config.endpoints.items()):
+            ref = f"{api_name}.{ep_name}"
+            method = ep_config.method.upper()
+            description = ep_config.description or ""
+
+            if filter_terms and not _matches_filter(filter_terms, ref, method, ep_config.path, description):
+                continue
+
+            results.append((api_name, ep_config))
+    return results
+
 
 def list_endpoints(
     api: Annotated[
@@ -21,7 +165,22 @@ def list_endpoints(
         typer.Option(
             "--verbose",
             "-v",
-            help="Show additional details (method, auth, headers).",
+            help="Show additional details (method, description, query params).",
+        ),
+    ] = False,
+    filter_str: Annotated[
+        str | None,
+        typer.Option(
+            "--filter",
+            "-f",
+            help="Filter endpoints by keyword(s). Searches in ref, method, path, description.",
+        ),
+    ] = None,
+    short_desc: Annotated[
+        bool,
+        typer.Option(
+            "--short-desc",
+            help="Truncate descriptions to 40 chars (verbose mode only).",
         ),
     ] = False,
 ) -> None:
@@ -34,8 +193,20 @@ def list_endpoints(
         # List endpoints for specific API
         kstlib rapi list github
 
-        # Verbose output with methods and auth
+        # Filter by keyword (searches everywhere)
+        kstlib rapi list --filter "delete"
+
+        # Multiple keywords (AND logic)
+        kstlib rapi list --filter "annotation GET"
+
+        # Combine API filter with keyword filter
+        kstlib rapi list annotations --filter "member"
+
+        # Verbose output with method, description, query params
         kstlib rapi list -v
+
+        # Show details for specific endpoint (use 'rapi show')
+        kstlib rapi show annotations.create
     """
     try:
         config_manager = load_rapi_config()
@@ -58,42 +229,33 @@ def list_endpoints(
             raise typer.Exit(code=1)
         apis = {api: apis[api]}
 
-    # Build table
-    if verbose:
-        table = Table(title="Available Endpoints", show_lines=True)
-        table.add_column("Reference", style="cyan")
-        table.add_column("Method", style="green")
-        table.add_column("Path")
-        table.add_column("Query", style="yellow")
-    else:
-        table = Table(title="Available Endpoints")
-        table.add_column("Reference", style="cyan")
-        table.add_column("Path")
+    # Parse filter terms
+    filter_terms = filter_str.lower().split() if filter_str else []
 
-    for api_name, api_config in sorted(apis.items()):
-        for ep_name, ep_config in sorted(api_config.endpoints.items()):
-            ref = f"{api_name}.{ep_name}"
+    # Collect matching endpoints
+    matches = _collect_matching_endpoints(apis, filter_terms)
 
-            # Build path display with query param indicator
-            path_display = f"[dim]{ep_config.path}[/]"
-            if ep_config.query:
-                path_display += f" [yellow]({len(ep_config.query)})[/]"
-
-            if verbose:
-                method = ep_config.method.upper()
-                # Show query param keys or "-"
-                query_info = ", ".join(ep_config.query.keys()) if ep_config.query else "-"
+    if not matches:
+        if filter_terms:
+            console.print(f"[yellow]No endpoints matching '{filter_str}'[/]")
+        else:
+            console.print("[yellow]No endpoints found.[/]")
+        raise typer.Exit(code=0)
 
-                table.add_row(ref, method, path_display, query_info)
-            else:
-                table.add_row(ref, path_display)
+    # Build and populate table
+    table = _create_table(verbose)
+    for api_name, ep_config in matches:
+        _add_endpoint_row(table, ep_config, api_name, verbose, short_desc=short_desc)
 
     console.print(table)
 
     # Summary
     total_apis = len(apis)
-    total_endpoints = sum(len(api.endpoints) for api in apis.values())
-    console.print(f"\n[dim]{total_endpoints} endpoints across {total_apis} API(s)[/]")
+    total_endpoints = sum(len(a.endpoints) for a in apis.values())
+    if filter_terms:
+        console.print(f"\n[dim]{len(matches)} matching / {total_endpoints} total endpoints[/]")
+    else:
+        console.print(f"\n[dim]{total_endpoints} endpoints across {total_apis} API(s)[/]")
 
 
 __all__ = ["list_endpoints"]

kstlib/cli/commands/secrets/common.py

@@ -222,6 +222,48 @@ def run_sops_command(binary: str, arguments: list[str]) -> CompletedProcess[str]
     )
 
 
+def find_sops_config(start_path: Path | None = None) -> Path | None:
+    """Find .sops.yaml by searching from start_path up to root, then home.
+
+    This mimics the native sops behavior which searches for configuration
+    files starting from the current directory and walking up to the root,
+    then falling back to the user home directory.
+
+    Args:
+        start_path: Directory to start searching from. If None, uses cwd.
+
+    Returns:
+        Path to .sops.yaml if found, None otherwise.
+    """
+    config_name = ".sops.yaml"
+
+    # Start from provided path or current working directory
+    if start_path is not None:
+        current = start_path.resolve()
+        if current.is_file():
+            current = current.parent
+    else:
+        current = Path.cwd()
+
+    # Walk up the directory tree
+    while True:
+        candidate = current / config_name
+        if candidate.is_file():
+            return candidate
+        parent = current.parent
+        if parent == current:
+            # Reached root
+            break
+        current = parent
+
+    # Fallback to home directory
+    home_config = Path.home() / config_name
+    if home_config.is_file():
+        return home_config
+
+    return None
+
+
 def resolve_sops_binary() -> str:
     """Return the configured sops binary name if set, otherwise the default."""
     default_binary = "sops"
@@ -418,6 +460,7 @@ __all__ = [
     "Path",
     "SecureDeleteCLIOptions",
     "ShredCommandOptions",
+    "find_sops_config",
     "format_arguments",
     "resolve_sops_binary",
     "run_sops_command",

kstlib/cli/commands/secrets/encrypt.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-from pathlib import Path
 from typing import TYPE_CHECKING
 
 import typer
@@ -31,7 +30,9 @@ from .common import (
     SHRED_PASSES_OPTION,
     SHRED_ZERO_LAST_OPTION,
     EncryptCommandOptions,
+    Path,
     SecureDeleteCLIOptions,
+    find_sops_config,
     format_arguments,
     resolve_sops_binary,
     run_sops_command,
@@ -213,9 +214,8 @@ def encrypt(
     binary = resolve_sops_binary()
     effective_config = config
     if effective_config is None:
-        default_config = Path.home() / ".sops.yaml"
-        if default_config.exists():
-            effective_config = default_config
+        # Search for .sops.yaml from source file directory up to root, then home
+        effective_config = find_sops_config(source)
 
     options = EncryptCommandOptions(
         out=out,

kstlib/kstlib.conf.yml

@@ -623,6 +623,17 @@ rapi:
     retry_delay: 1.0           # Initial delay between retries (seconds)
     retry_backoff: 2.0         # Exponential backoff multiplier
 
+  # Safeguard configuration for dangerous HTTP methods
+  # Endpoints using these methods MUST define a safeguard string
+  # to prevent accidental destructive operations
+  safeguard:
+    # HTTP methods that require a safeguard to be defined on endpoints
+    # Default: DELETE and PUT (most destructive operations)
+    # Set to empty list [] to disable safeguard requirements
+    required_methods:
+      - DELETE
+      - PUT
+
   # Pretty-print settings for CLI output
   # Controls formatting of JSON and XML responses in terminal
   pretty_render:

kstlib/meta.py

@@ -39,7 +39,7 @@ __logo__ = (
 )
 
 __app_name__ = "kstlib"
-__version__ = "1.0.2"
+__version__ = "1.1.1"
 __description__ = (
     "Config-driven helpers for Python projects (dynamic config, secure secrets, preset logging, and more…)"
 )

kstlib/rapi/__init__.py

@@ -85,26 +85,32 @@ from kstlib.rapi.config import (
     EndpointConfig,
     HmacConfig,
     RapiConfigManager,
+    SafeguardConfig,
     load_rapi_config,
 )
 from kstlib.rapi.credentials import CredentialRecord, CredentialResolver
 from kstlib.rapi.exceptions import (
+    ConfirmationRequiredError,
     CredentialError,
     EndpointAmbiguousError,
     EndpointNotFoundError,
+    EnvVarError,
     RapiError,
     RequestError,
     ResponseTooLargeError,
+    SafeguardMissingError,
 )
 
 __all__ = [
     "ApiConfig",
+    "ConfirmationRequiredError",
     "CredentialError",
     "CredentialRecord",
     "CredentialResolver",
     "EndpointAmbiguousError",
     "EndpointConfig",
     "EndpointNotFoundError",
+    "EnvVarError",
     "HmacConfig",
     "RapiClient",
     "RapiConfigManager",
@@ -112,6 +118,8 @@ __all__ = [
     "RapiResponse",
     "RequestError",
     "ResponseTooLargeError",
+    "SafeguardConfig",
+    "SafeguardMissingError",
     "call",
     "call_async",
     "load_rapi_config",

kstlib/rapi/client.py

@@ -27,6 +27,7 @@ from kstlib.rapi.config import (
 )
 from kstlib.rapi.credentials import CredentialRecord, CredentialResolver
 from kstlib.rapi.exceptions import (
+    ConfirmationRequiredError,
     RequestError,
     ResponseTooLargeError,
 )
@@ -45,6 +46,37 @@ def _log_trace(msg: str, *args: Any) -> None:
     log.log(TRACE_LEVEL, msg, *args)
 
 
+def _validate_safeguard(
+    endpoint_config: EndpointConfig,
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    confirm: str | None,
+) -> None:
+    """Validate safeguard confirmation for dangerous endpoints.
+
+    Args:
+        endpoint_config: Endpoint configuration.
+        args: Positional arguments for path/safeguard substitution.
+        kwargs: Keyword arguments for path/safeguard substitution.
+        confirm: Confirmation string provided by caller.
+
+    Raises:
+        ConfirmationRequiredError: If safeguard is required but confirm is missing or wrong.
+    """
+    if endpoint_config.safeguard is None:
+        return
+
+    expected = endpoint_config.build_safeguard(*args, **kwargs)
+    if expected is None:
+        return
+
+    if confirm is None:
+        raise ConfirmationRequiredError(endpoint_config.full_ref, expected=expected)
+
+    if confirm != expected:
+        raise ConfirmationRequiredError(endpoint_config.full_ref, expected=expected, actual=confirm)
+
+
 @dataclass
 class RapiResponse:
     """Response from an API call.
@@ -238,6 +270,7 @@ class RapiClient:
         body: Any = None,
         headers: Mapping[str, str] | None = None,
         timeout: float | None = None,
+        confirm: str | None = None,
         **kwargs: Any,
     ) -> RapiResponse:
         """Make a synchronous API call.
@@ -248,12 +281,14 @@ class RapiClient:
             body: Request body (dict for JSON, str for raw).
             headers: Runtime headers (override service/endpoint headers).
             timeout: Request timeout (uses config default if None).
+            confirm: Confirmation string for dangerous endpoints with safeguard.
             **kwargs: Keyword arguments for path parameters and query params.
 
         Returns:
             RapiResponse with parsed data.
 
         Raises:
+            ConfirmationRequiredError: If safeguard requires confirmation.
             RequestError: If request fails after retries.
             ResponseTooLargeError: If response exceeds max size.
 
@@ -262,6 +297,7 @@ class RapiClient:
             >>> client.call("httpbin.get_ip")  # doctest: +SKIP
             >>> client.call("httpbin.delayed", 5)  # doctest: +SKIP
             >>> client.call("httpbin.post_data", body={"key": "value"})  # doctest: +SKIP
+            >>> client.call("admin.delete_user", userId="123", confirm="DELETE USER 123")  # doctest: +SKIP
         """
         log.debug("Calling endpoint: %s", endpoint_ref)
 
@@ -269,6 +305,9 @@ class RapiClient:
         api_config, endpoint_config = self._config_manager.resolve(endpoint_ref)
         _log_trace("Resolved to: %s", endpoint_config.full_ref)
 
+        # Validate safeguard before proceeding
+        _validate_safeguard(endpoint_config, args, kwargs, confirm)
+
         # Build request
         request = self._build_request(
             api_config,
@@ -290,6 +329,7 @@ class RapiClient:
         body: Any = None,
         headers: Mapping[str, str] | None = None,
         timeout: float | None = None,
+        confirm: str | None = None,
         **kwargs: Any,
     ) -> RapiResponse:
         """Make an asynchronous API call.
@@ -300,12 +340,14 @@ class RapiClient:
             body: Request body (dict for JSON, str for raw).
             headers: Runtime headers (override service/endpoint headers).
             timeout: Request timeout (uses config default if None).
+            confirm: Confirmation string for dangerous endpoints with safeguard.
             **kwargs: Keyword arguments for path parameters and query params.
 
         Returns:
             RapiResponse with parsed data.
 
         Raises:
+            ConfirmationRequiredError: If safeguard requires confirmation.
             RequestError: If request fails after retries.
             ResponseTooLargeError: If response exceeds max size.
         """
@@ -315,6 +357,9 @@ class RapiClient:
         api_config, endpoint_config = self._config_manager.resolve(endpoint_ref)
         _log_trace("Resolved to: %s", endpoint_config.full_ref)
 
+        # Validate safeguard before proceeding
+        _validate_safeguard(endpoint_config, args, kwargs, confirm)
+
         # Build request
         request = self._build_request(
             api_config,
@@ -814,6 +859,7 @@ def call(
     *args: Any,
     body: Any = None,
     headers: Mapping[str, str] | None = None,
+    confirm: str | None = None,
     **kwargs: Any,
 ) -> RapiResponse:
     """Convenience function for quick API calls.
@@ -825,6 +871,7 @@ def call(
         *args: Positional path parameters.
         body: Request body.
         headers: Runtime headers.
+        confirm: Confirmation string for dangerous endpoints with safeguard.
         **kwargs: Keyword parameters.
 
     Returns:
@@ -835,7 +882,7 @@ def call(
         >>> response = call("httpbin.get_ip")  # doctest: +SKIP
     """
     client = RapiClient()
-    return client.call(endpoint_ref, *args, body=body, headers=headers, **kwargs)
+    return client.call(endpoint_ref, *args, body=body, headers=headers, confirm=confirm, **kwargs)
 
 
 async def call_async(
@@ -843,6 +890,7 @@ async def call_async(
     *args: Any,
     body: Any = None,
     headers: Mapping[str, str] | None = None,
+    confirm: str | None = None,
     **kwargs: Any,
 ) -> RapiResponse:
     """Convenience function for async API calls.
@@ -854,6 +902,7 @@ async def call_async(
         *args: Positional path parameters.
         body: Request body.
         headers: Runtime headers.
+        confirm: Confirmation string for dangerous endpoints with safeguard.
         **kwargs: Keyword parameters.
 
     Returns:
@@ -864,7 +913,7 @@ async def call_async(
         >>> response = await call_async("httpbin.get_ip")  # doctest: +SKIP
     """
     client = RapiClient()
-    return await client.call_async(endpoint_ref, *args, body=body, headers=headers, **kwargs)
+    return await client.call_async(endpoint_ref, *args, body=body, headers=headers, confirm=confirm, **kwargs)
 
 
 __all__ = [