kstlib 0.0.1a0__py3-none-any.whl → 1.0.1__py3-none-any.whl

kstlib/cli/commands/rapi/call.py

@@ -0,0 +1,341 @@
+"""Make API calls from the command line."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated, Any, cast
+
+import typer
+
+from kstlib.cli.common import CommandResult, CommandStatus, console, exit_error, exit_with_result
+from kstlib.limits import get_rapi_render_config
+from kstlib.rapi import (
+    CredentialError,
+    EndpointAmbiguousError,
+    EndpointNotFoundError,
+    RapiClient,
+    RapiResponse,
+    RequestError,
+    ResponseTooLargeError,
+    load_rapi_config,
+)
+from kstlib.utils.serialization import is_xml_content, to_json, to_xml
+
+
+def _parse_args(
+    args: list[str],
+) -> tuple[list[str], dict[str, str]]:
+    """Parse positional and keyword arguments.
+
+    Args:
+        args: List of arguments like ["3", "foo=bar", "count=42"].
+
+    Returns:
+        Tuple of (positional_args, keyword_args).
+
+    Examples:
+        >>> _parse_args(["3", "foo=bar", "count=42"])
+        (['3'], {'foo': 'bar', 'count': '42'})
+        >>> _parse_args(["value1", "value2"])
+        (['value1', 'value2'], {})
+    """
+    positional: list[str] = []
+    keyword: dict[str, str] = {}
+
+    for arg in args:
+        if "=" in arg:
+            key, value = arg.split("=", 1)
+            keyword[key] = value
+        else:
+            positional.append(arg)
+
+    return positional, keyword
+
+
+def _parse_headers(headers: list[str]) -> dict[str, str]:
+    """Parse header arguments.
+
+    Args:
+        headers: List of headers like ["Accept: application/json", "X-Debug: true"].
+
+    Returns:
+        Dictionary of header name to value.
+
+    Raises:
+        typer.Exit: If header format is invalid.
+    """
+    result: dict[str, str] = {}
+    for header in headers:
+        if ":" not in header:
+            exit_error(f"Invalid header format: '{header}'\nExpected: 'Header-Name: value'")
+        name, value = header.split(":", 1)
+        result[name.strip()] = value.strip()
+    return result
+
+
+def _parse_body(body: str | None) -> dict[str, Any] | list[Any] | None:
+    """Parse JSON body string or load from file.
+
+    Supports reading from file with @filename syntax (like curl).
+
+    Args:
+        body: JSON string, @filename reference, or None.
+
+    Returns:
+        Parsed JSON object or None.
+
+    Raises:
+        typer.Exit: If body is not valid JSON or file not found.
+
+    Examples:
+        >>> _parse_body('{"key": "value"}')
+        {'key': 'value'}
+        >>> _parse_body('@data.json')  # Reads from file
+        {'key': 'value'}
+    """
+    if body is None:
+        return None
+
+    # Support @filename syntax (like curl)
+    if body.startswith("@"):
+        from pathlib import Path
+
+        filepath = Path(body[1:])
+        try:
+            content = filepath.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            exit_error(f"Body file not found: {filepath}")
+        except OSError as e:
+            exit_error(f"Failed to read body file '{filepath}': {e}")
+    else:
+        content = body
+
+    try:
+        return json.loads(content)  # type: ignore[no-any-return]
+    except json.JSONDecodeError as e:
+        exit_error(f"Invalid JSON body: {e}")
+
+
+def _format_output(
+    response: RapiResponse,
+    fmt: str,
+    quiet: bool,
+    out_file: str | None = None,
+) -> None:
+    """Format and print response output.
+
+    Args:
+        response: The API response to format.
+        fmt: Output format (json, text, full).
+        quiet: Whether to suppress rich formatting.
+        out_file: Optional file path to write output to.
+    """
+    # Load render config for pretty-print settings
+    render_config = get_rapi_render_config()
+    content_type = response.headers.get("content-type", "")
+
+    # Build output content
+    if fmt == "full":
+        result_data = {
+            "endpoint": response.endpoint_ref,
+            "status_code": response.status_code,
+            "ok": response.ok,
+            "elapsed": f"{response.elapsed:.3f}s",
+            "headers": dict(response.headers),
+            "data": response.data,
+        }
+        content = to_json(result_data, indent=render_config.json_indent or 2)
+    elif fmt == "text":
+        # Text format: apply XML pretty-print if enabled and content is XML
+        if render_config.xml_pretty and is_xml_content(response.text, content_type):
+            content = to_xml(response.text)
+        else:
+            content = response.text
+    elif response.data is not None:
+        # JSON data available: format with configured indent
+        content = to_json(response.data, indent=render_config.json_indent or 2)
+    elif render_config.xml_pretty and is_xml_content(response.text, content_type):
+        # No JSON data but XML detected: pretty-print if enabled
+        content = to_xml(response.text)
+    else:
+        # Raw text fallback
+        content = response.text
+
+    # Write to file or print
+    if out_file:
+        from pathlib import Path
+
+        Path(out_file).write_text(content, encoding="utf-8")
+        if not quiet:
+            console.print(f"[green]Output written to:[/green] {out_file}")
+    elif quiet or fmt == "text" or (fmt == "json" and response.data is None):
+        print(content)
+    else:
+        console.print_json(content)
+
+
+def call(
+    endpoint: Annotated[
+        str,
+        typer.Argument(help="Endpoint reference (e.g., 'github.user' or 'api.endpoint')."),
+    ],
+    args: Annotated[
+        list[str] | None,
+        typer.Argument(
+            help="Path/query params: positional for path, key=value for query.",
+        ),
+    ] = None,
+    body: Annotated[
+        str | None,
+        typer.Option(
+            "--body",
+            "-b",
+            help="JSON body or @filename to read from file.",
+        ),
+    ] = None,
+    header: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--header",
+            "-H",
+            help="Custom header (can be repeated). Format: 'Name: value'.",
+        ),
+    ] = None,
+    fmt: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            "-f",
+            help="Output format: json, text, or full.",
+        ),
+    ] = "json",
+    out: Annotated[
+        str | None,
+        typer.Option(
+            "--out",
+            "-o",
+            help="Write output to file (for scripting).",
+        ),
+    ] = None,
+    quiet: Annotated[
+        bool,
+        typer.Option(
+            "--quiet",
+            "-q",
+            help="Suppress status messages, only output response.",
+        ),
+    ] = False,
+) -> None:
+    """Make an API call to a configured endpoint.
+
+    Examples:
+        # Simple GET (implicit call)
+        kstlib rapi github.user
+
+        # GET with path parameters
+        kstlib rapi github.repos-get owner=KaminoU repo=igcv3
+
+        # POST with JSON body from file (recommended for complex JSON)
+        kstlib rapi myapi.create-item -b @data.json
+
+        # Custom headers
+        kstlib rapi github.user -H "X-Debug: true"
+
+        # Output to file (for scripting)
+        kstlib rapi github.user -o user.json
+
+        # Full format with file output
+        kstlib rapi github.user -f full -o result.json
+
+        # Quiet mode (JSON only, no formatting)
+        kstlib rapi github.rate-limit -q
+    """
+    # Parse arguments
+    positional_args, keyword_args = _parse_args(args or [])
+    headers = _parse_headers(header or [])
+    parsed_body = _parse_body(body)
+
+    # Validate output format
+    if fmt not in ("json", "text", "full"):
+        exit_error(f"Invalid output format: '{fmt}'\nValid formats: json, text, full")
+
+    try:
+        # Create client and make call
+        config_manager = load_rapi_config()
+        client = RapiClient(config_manager=config_manager)
+
+        response = client.call(
+            endpoint,
+            *positional_args,
+            body=parsed_body,
+            headers=headers if headers else None,
+            **cast("dict[str, Any]", keyword_args),
+        )
+
+        # Format and print output
+        _format_output(response, fmt, quiet, out)
+
+        # Exit with appropriate code
+        if not response.ok:
+            raise typer.Exit(code=1)
+
+    except EndpointNotFoundError as e:
+        exit_with_result(
+            CommandResult(
+                status=CommandStatus.ERROR,
+                message=f"Endpoint not found: {e.endpoint_ref}",
+                payload={"searched_apis": e.searched_apis} if e.searched_apis else None,
+            ),
+            quiet=quiet,
+            exit_code=1,
+            cause=e,
+        )
+    except EndpointAmbiguousError as e:
+        exit_with_result(
+            CommandResult(
+                status=CommandStatus.ERROR,
+                message=f"Ambiguous endpoint: '{e.endpoint_name}' exists in multiple APIs",
+                payload={"matching_apis": e.matching_apis},
+            ),
+            quiet=quiet,
+            exit_code=1,
+            cause=e,
+        )
+    except CredentialError as e:
+        exit_with_result(
+            CommandResult(
+                status=CommandStatus.ERROR,
+                message=f"Credential error: {e}",
+                payload={"credential_name": e.credential_name} if e.credential_name else None,
+            ),
+            quiet=quiet,
+            exit_code=1,
+            cause=e,
+        )
+    except RequestError as e:
+        exit_with_result(
+            CommandResult(
+                status=CommandStatus.ERROR,
+                message=f"Request failed: {e}",
+                payload={
+                    "status_code": e.status_code,
+                    "retryable": e.retryable,
+                },
+            ),
+            quiet=quiet,
+            exit_code=1,
+            cause=e,
+        )
+    except ResponseTooLargeError as e:
+        exit_with_result(
+            CommandResult(
+                status=CommandStatus.ERROR,
+                message=f"Response too large: {e.response_size} bytes (max: {e.max_size})",
+            ),
+            quiet=quiet,
+            exit_code=1,
+            cause=e,
+        )
+
+
+__all__ = ["call"]

kstlib/cli/commands/rapi/list.py

@@ -0,0 +1,99 @@
+"""List available API endpoints."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.table import Table
+
+from kstlib.cli.common import console
+from kstlib.rapi import load_rapi_config
+
+
+def list_endpoints(
+    api: Annotated[
+        str | None,
+        typer.Argument(help="Filter by API name (optional)."),
+    ] = None,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Show additional details (method, auth, headers).",
+        ),
+    ] = False,
+) -> None:
+    """List all configured API endpoints.
+
+    Examples:
+        # List all endpoints
+        kstlib rapi list
+
+        # List endpoints for specific API
+        kstlib rapi list github
+
+        # Verbose output with methods and auth
+        kstlib rapi list -v
+    """
+    try:
+        config_manager = load_rapi_config()
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        console.print(f"[red]Failed to load rapi config: {e}[/]")
+        raise typer.Exit(code=1) from e
+
+    apis = config_manager.apis
+
+    if not apis:
+        console.print("[yellow]No APIs configured in kstlib.conf.yml[/]")
+        console.print("[dim]Add APIs under 'rapi.api' section.[/]")
+        raise typer.Exit(code=0)
+
+    # Filter by API name if specified
+    if api:
+        if api not in apis:
+            console.print(f"[red]API '{api}' not found.[/]")
+            console.print(f"[dim]Available APIs: {', '.join(apis.keys())}[/]")
+            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")
+
+    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}"
+
+            # 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 "-"
+
+                table.add_row(ref, method, path_display, query_info)
+            else:
+                table.add_row(ref, path_display)
+
+    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)[/]")
+
+
+__all__ = ["list_endpoints"]

kstlib/cli/commands/rapi/show.py

@@ -0,0 +1,206 @@
+"""Show detailed information for a specific API endpoint."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+from rich.markup import escape
+from rich.panel import Panel
+from rich.table import Table
+
+from kstlib.cli.common import console
+from kstlib.limits import HARD_MAX_DISPLAY_VALUE_LENGTH, HARD_MAX_ENDPOINT_REF_LENGTH
+from kstlib.rapi import EndpointNotFoundError, load_rapi_config
+from kstlib.rapi.config import _PATH_PARAM_PATTERN
+
+if TYPE_CHECKING:
+    from kstlib.rapi.config import ApiConfig, EndpointConfig
+
+# Allowed characters for endpoint reference: alphanum + underscore + dot + hyphen
+_ENDPOINT_REF_PATTERN = re.compile(r"^[a-zA-Z0-9_.-]+$")
+
+
+def _truncate(value: str, max_length: int = HARD_MAX_DISPLAY_VALUE_LENGTH) -> str:
+    """Truncate a string and append ellipsis if too long."""
+    if len(value) <= max_length:
+        return value
+    return value[: max_length - 3] + "..."
+
+
+def _validate_endpoint_ref(endpoint_ref: str) -> None:
+    """Validate endpoint reference for security (deep defense)."""
+    if len(endpoint_ref) > HARD_MAX_ENDPOINT_REF_LENGTH:
+        console.print(f"[red]Endpoint reference too long: {len(endpoint_ref)} > {HARD_MAX_ENDPOINT_REF_LENGTH}[/]")
+        raise typer.Exit(code=1)
+
+    if not _ENDPOINT_REF_PATTERN.match(endpoint_ref):
+        console.print("[red]Endpoint reference contains invalid characters.[/]")
+        console.print("[dim]Allowed: alphanumeric, underscore, dot, hyphen[/]")
+        raise typer.Exit(code=1)
+
+
+def _print_basic_info(api_config: ApiConfig, ep_config: EndpointConfig) -> None:
+    """Print basic endpoint information table."""
+    info_table = Table(show_header=False, box=None, padding=(0, 2))
+    info_table.add_column("Label", style="dim")
+    info_table.add_column("Value")
+
+    info_table.add_row("Path:", f"[green]{escape(ep_config.path)}[/]")
+    info_table.add_row("Method:", f"[yellow]{ep_config.method}[/]")
+    info_table.add_row("API:", api_config.name)
+    info_table.add_row("Base URL:", escape(api_config.base_url))
+
+    console.print(info_table)
+    console.print()
+
+
+def _print_path_params(path_params: list[str]) -> None:
+    """Print path parameters section."""
+    console.print("[bold]Path Parameters:[/]")
+    if path_params:
+        for param in path_params:
+            suffix = " [dim](positional)[/]" if param.isdigit() else ""
+            console.print(f"  [cyan]{{{param}}}[/]{suffix}")
+    else:
+        console.print("  [dim](none)[/]")
+    console.print()
+
+
+def _print_query_params(ep_config: EndpointConfig) -> None:
+    """Print default query parameters section."""
+    console.print("[bold]Default Query Parameters:[/]")
+    if ep_config.query:
+        for key, value in ep_config.query.items():
+            safe_value = escape(_truncate(str(value)))
+            console.print(f"  [cyan]{escape(key)}[/] = {safe_value}")
+    else:
+        console.print("  [dim](none)[/]")
+    console.print()
+
+
+def _print_headers(api_config: ApiConfig, ep_config: EndpointConfig) -> None:
+    """Print headers section."""
+    console.print("[bold]Headers:[/]")
+    service_headers = len(api_config.headers) if api_config.headers else 0
+    ep_headers = len(ep_config.headers) if ep_config.headers else 0
+    console.print(f"  Service: [dim]{service_headers} header(s)[/]")
+    console.print(f"  Endpoint: [dim]{ep_headers} header(s)[/]")
+    console.print()
+
+
+def _print_auth(api_config: ApiConfig, ep_config: EndpointConfig) -> None:
+    """Print authentication section."""
+    console.print("[bold]Authentication:[/]")
+    if api_config.auth_type:
+        console.print("  Required: [yellow]Yes[/]")
+        console.print(f"  Type: [cyan]{api_config.auth_type}[/]")
+        if ep_config.auth is False:
+            console.print("  [dim]Note: Auth disabled for this endpoint[/]")
+    else:
+        console.print("  Required: [green]No[/]")
+    console.print()
+
+
+def _print_body_template(ep_config: EndpointConfig) -> None:
+    """Print body template section."""
+    console.print("[bold]Body Template:[/]")
+    if ep_config.body_template:
+        body_str = json.dumps(ep_config.body_template, indent=2)
+        safe_body = escape(_truncate(body_str))
+        console.print(f"  {safe_body}")
+    elif ep_config.method in ("POST", "PUT", "PATCH"):
+        console.print("  [dim](none - provide via --body)[/]")
+    else:
+        console.print(f"  [dim](none - {ep_config.method} request)[/]")
+    console.print()
+
+
+def _print_examples(ep_config: EndpointConfig, path_params: list[str]) -> None:
+    """Print usage examples section."""
+    console.print("[bold]Examples:[/]")
+    base_cmd = f"kstlib rapi {ep_config.full_ref}"
+
+    # Build path params string (required in ALL examples)
+    # Use escape() to prevent Rich from interpreting <param> as markup tags
+    path_args = ""
+    if path_params:
+        named_args = " ".join(escape(f"<{p}>") for p in path_params if not p.isdigit())
+        positional_args = " ".join(escape(f"<arg{p}>") for p in path_params if p.isdigit())
+        path_args = " ".join(filter(None, [named_args, positional_args]))
+
+    # Basic example with required path params
+    if path_args:
+        console.print(f"  [dim]{base_cmd} {path_args}[/]")
+    else:
+        console.print(f"  [dim]{base_cmd}[/]")
+
+    # Example with query param (path params are REQUIRED, query is optional)
+    if ep_config.query:
+        first_key = escape(next(iter(ep_config.query)))
+        if path_args:
+            console.print(f"  [dim]{base_cmd} {path_args} {first_key}={escape('<value>')}[/]")
+        else:
+            console.print(f"  [dim]{base_cmd} {first_key}={escape('<value>')}[/]")
+
+    # Example with body (path params are REQUIRED)
+    if ep_config.method in ("POST", "PUT", "PATCH"):
+        if path_args:
+            console.print(f'  [dim]{base_cmd} {path_args} --body \'{{"key": "value"}}\'[/]')
+        else:
+            console.print(f'  [dim]{base_cmd} --body \'{{"key": "value"}}\'[/]')
+
+    console.print()
+
+
+def show_endpoint(
+    endpoint_ref: Annotated[
+        str,
+        typer.Argument(help="Endpoint reference (api.endpoint or short form)."),
+    ],
+) -> None:
+    """Show detailed information for an API endpoint.
+
+    Displays full configuration including path parameters, query parameters,
+    headers, authentication requirements, and usage examples.
+
+    Examples:
+        # Show endpoint details
+        kstlib rapi show httpbin.get_ip
+
+        # Short form (if unique)
+        kstlib rapi show get_ip
+    """
+    _validate_endpoint_ref(endpoint_ref)
+
+    try:
+        config_manager = load_rapi_config()
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        console.print(f"[red]Failed to load rapi config: {e}[/]")
+        raise typer.Exit(code=1) from e
+
+    try:
+        api_config, ep_config = config_manager.resolve(endpoint_ref)
+    except EndpointNotFoundError as e:
+        console.print(f"[red]Endpoint not found: {endpoint_ref}[/]")
+        console.print(f"[dim]Available APIs: {', '.join(e.searched_apis)}[/]")
+        raise typer.Exit(code=1) from e
+
+    path_params = _PATH_PARAM_PATTERN.findall(ep_config.path)
+
+    console.print()
+    console.print(Panel(f"[bold cyan]{ep_config.full_ref}[/]", expand=False))
+    console.print()
+
+    _print_basic_info(api_config, ep_config)
+    _print_path_params(path_params)
+    _print_query_params(ep_config)
+    _print_headers(api_config, ep_config)
+    _print_auth(api_config, ep_config)
+    _print_body_template(ep_config)
+    _print_examples(ep_config, path_params)
+
+
+__all__ = ["show_endpoint"]

kstlib/cli/commands/secrets/__init__.py

@@ -0,0 +1,35 @@
+"""CLI commands for secrets management."""
+
+from __future__ import annotations
+
+import typer
+
+from .decrypt import decrypt
+from .doctor import doctor, init
+from .encrypt import encrypt
+from .shred import shred
+
+secrets_app = typer.Typer(help="Manage encrypted secrets and diagnostics.")
+
+# Register commands on the secrets_app
+secrets_app.command()(doctor)
+secrets_app.command()(init)
+secrets_app.command()(encrypt)
+secrets_app.command()(decrypt)
+secrets_app.command()(shred)
+
+
+def register_cli(app: typer.Typer) -> None:
+    """Register the secrets sub-commands on the root Typer app."""
+    app.add_typer(secrets_app, name="secrets")
+
+
+__all__ = [
+    "decrypt",
+    "doctor",
+    "encrypt",
+    "init",
+    "register_cli",
+    "secrets_app",
+    "shred",
+]