linc-cli-kit 0.1.1__py3-none-any.whl

linc_cli_kit/__init__.py

@@ -0,0 +1,65 @@
+"""linc-cli-kit — FastMCP registry → Click commands under one output contract.
+
+Import cost is paid by every adopter CLI invocation, `--help` included, so the conformance
+suite (`assert_cli_parity`, `ParityReport`: click.testing + unittest.mock) loads on first
+attribute access (PEP 562), and `transport` imports httpx/anyio only when a call needs them.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from linc_cli_kit.errors import ToolError, UsageError, parse_error_envelope
+from linc_cli_kit.logging import configure_stderr_logging, configure_structlog_stderr
+from linc_cli_kit.mount import (
+    current_mode,
+    current_output,
+    current_timeout,
+    install_globals,
+    mount_tools,
+)
+from linc_cli_kit.output import emit, emit_exception, heartbeat, json_default, to_json
+from linc_cli_kit.registry import ToolSpec, registry_of
+from linc_cli_kit.transport import HttpDaemonTransport, LocalTransport
+
+if TYPE_CHECKING:
+    from linc_cli_kit.testing import ParityReport, assert_cli_parity
+
+_LAZY = {"ParityReport": "linc_cli_kit.testing", "assert_cli_parity": "linc_cli_kit.testing"}
+
+__all__ = [
+    "HttpDaemonTransport",
+    "LocalTransport",
+    "ParityReport",
+    "ToolError",
+    "ToolSpec",
+    "UsageError",
+    "assert_cli_parity",
+    "configure_stderr_logging",
+    "configure_structlog_stderr",
+    "current_mode",
+    "current_output",
+    "current_timeout",
+    "emit",
+    "emit_exception",
+    "heartbeat",
+    "install_globals",
+    "json_default",
+    "mount_tools",
+    "parse_error_envelope",
+    "registry_of",
+    "to_json",
+]
+
+
+def __getattr__(name: str) -> Any:
+    module = _LAZY.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    value = getattr(importlib.import_module(module), name)
+    globals()[name] = value  # cache: later lookups skip __getattr__
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))

linc_cli_kit/errors.py

@@ -0,0 +1,136 @@
+"""Error envelope + exit-code classification (spec §5.2)."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+CATEGORIES = (
+    "validation",
+    "not_found",
+    "permission",
+    "unavailable",
+    "upstream_timeout",
+    "internal",
+)
+_RETRYABLE = {"unavailable", "upstream_timeout"}
+
+
+class ToolError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "TOOL_ERROR",
+        hint: str = "",
+        category: str = "internal",
+        retryable: bool | None = None,
+        details: dict[str, Any] | None = None,
+        exit_code: int = 1,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.hint = hint
+        self.category = category if category in CATEGORIES else "internal"
+        self.retryable = (self.category in _RETRYABLE) if retryable is None else retryable
+        self.details = details or {}
+        self.exit_code = exit_code
+
+    def envelope(self) -> dict[str, Any]:
+        return {"error": {
+            "code": self.code, "message": self.message, "hint": self.hint,
+            "category": self.category, "retryable": self.retryable, "details": self.details,
+        }}
+
+
+class UsageError(ToolError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        hint: str = "",
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            code="USAGE_ERROR",
+            hint=hint,
+            category="validation",
+            retryable=False,
+            details=details,
+            exit_code=2,
+        )
+
+
+@dataclass(frozen=True)
+class Outcome:
+    exit_code: int
+    payload: Any
+    envelope: dict[str, Any] | None = field(default=None)
+
+
+def safe_str(value: Any) -> str:
+    """str() that cannot raise: the error path must not fail on a hostile __str__."""
+    try:
+        return str(value)
+    except Exception:
+        try:
+            return repr(value)
+        except Exception:
+            return f"<unprintable {type(value).__name__}>"
+
+
+def _upper_snake(name: str) -> str:
+    return re.sub(r"(?<!^)(?=[A-Z])", "_", name).upper()
+
+
+def classify(result: Any) -> Outcome:
+    """Map a tool's return value to an Outcome using the fleet's dict conventions."""
+    if result is None:
+        return Outcome(0, {}, None)
+    # Truthiness, not key presence: tools that always include an "error" key and set it to
+    # None/"" on success must classify as success (fleet convention).
+    if isinstance(result, dict) and result.get("error"):
+        validation = bool(result.get("validation_error"))
+        err = ToolError(
+            safe_str(result["error"]),
+            code="VALIDATION_ERROR" if validation else "TOOL_ERROR",
+            category="validation" if validation else "internal",
+            details={k: v for k, v in result.items() if k not in ("error", "validation_error")},
+            exit_code=2 if validation else 1,
+        )
+        return Outcome(err.exit_code, None, err.envelope())
+    return Outcome(0, result, None)
+
+
+def parse_error_envelope(stderr: str) -> dict[str, Any] | None:
+    """Return the error envelope from a command's stderr, or None if it wrote none.
+
+    The contract: on failure the envelope is the LAST line of stderr. Lines before it may be
+    JSON heartbeats (`{"event": "heartbeat", ...}`) or stderr logging, so never
+    `json.loads` the whole stream — take the last line that parses as an object with an
+    "error" key, which is what this does.
+    """
+    for line in reversed(stderr.splitlines()):
+        line = line.strip()
+        if not line.startswith("{"):
+            continue
+        try:
+            doc = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(doc, dict) and isinstance(doc.get("error"), dict):
+            return doc
+    return None
+
+
+def classify_exception(exc: BaseException) -> Outcome:
+    if isinstance(exc, ToolError):
+        return Outcome(exc.exit_code, None, exc.envelope())
+    err = ToolError(
+        safe_str(exc) or exc.__class__.__name__, code=_upper_snake(exc.__class__.__name__)
+    )
+    return Outcome(1, None, err.envelope())

linc_cli_kit/logging.py

@@ -0,0 +1,34 @@
+"""stderr-only logging, the sentinel pattern."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+
+def configure_stderr_logging(level: str | None = None) -> None:
+    name = (level or os.environ.get("LINC_LOG_LEVEL") or "WARNING").upper()
+    root = logging.getLogger()
+    for handler in list(root.handlers):
+        root.removeHandler(handler)
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("%(levelname)s %(name)s: %(message)s"))
+    root.addHandler(handler)
+    root.setLevel(getattr(logging, name, logging.WARNING))
+
+
+def configure_structlog_stderr() -> bool:
+    """Point structlog's default logger factory at stderr; no-op if structlog is absent.
+
+    Returns True if structlog was configured, False if it is not installed. The kit has no
+    hard dependency on structlog — the import happens inside the function so adopters that
+    do not use it pay nothing. Call this ABOVE your package imports: modules bind their
+    logger at import time, so a later call leaves already-bound loggers on stdout.
+    """
+    try:
+        import structlog
+    except ImportError:
+        return False
+    structlog.configure(logger_factory=structlog.PrintLoggerFactory(file=sys.stderr))
+    return True

linc_cli_kit/mount.py

@@ -0,0 +1,287 @@
+"""Mount a FastMCP registry onto a Click group (spec §5.1, §5.3, §5.5)."""
+
+from __future__ import annotations
+
+import functools
+import sys
+from collections.abc import Callable
+from typing import Any
+
+import click
+
+from linc_cli_kit.errors import ToolError, UsageError
+from linc_cli_kit.logging import configure_stderr_logging
+from linc_cli_kit.output import (
+    emit,
+    emit_exception,
+    harden_streams,
+    heartbeat,
+    resolve_mode,
+    to_json,
+)
+from linc_cli_kit.registry import ToolSpec, registry_of
+from linc_cli_kit.schema import cli_name, options_for
+from linc_cli_kit.transport import LocalTransport, Transport
+
+_META = "linc_cli_kit."
+
+# click.ParamType.name -> the schema doc's normalized "type" string (ruling 4).
+_TYPE_NAMES = {
+    "text": "STRING",
+    "integer": "INT",
+    "float": "FLOAT",
+    "boolean": "BOOL",
+    "choice": "CHOICE",
+    "json": "JSON",
+    "value": "VALUE",
+}
+
+
+def current_mode() -> str:
+    ctx = click.get_current_context(silent=True)
+    if ctx is not None:
+        mode = ctx.find_root().meta.get(_META + "mode")
+        if mode is not None:
+            return mode
+    return resolve_mode(None)
+
+
+def current_output() -> str | None:
+    ctx = click.get_current_context(silent=True)
+    return ctx.find_root().meta.get(_META + "output") if ctx is not None else None
+
+
+def current_timeout() -> float | None:
+    ctx = click.get_current_context(silent=True)
+    return ctx.find_root().meta.get(_META + "timeout") if ctx is not None else None
+
+
+def install_globals(group: click.Group) -> click.Group:
+    """Add the kit's global options and stream/logging hardening to an existing group."""
+    if any(getattr(p, "name", None) == "linc_mode" for p in group.params):
+        return group
+
+    # Built fresh per call (ruling 1) — Option instances must not be shared across groups.
+    global_options: list[click.Option] = [
+        click.Option(
+            ["--json", "linc_mode"], flag_value="json", default=None,
+            help="JSON on stdout (default).",
+        ),
+        click.Option(["--human", "linc_mode"], flag_value="human", help="Human rendering."),
+        click.Option(
+            ["--stream", "linc_mode"], flag_value="jsonl",
+            help="JSON Lines, one record per line.",
+        ),
+        click.Option(
+            ["--output", "-o", "linc_output"], default=None, help="Path for binary artifacts.",
+        ),
+        click.Option(
+            ["--timeout", "linc_timeout"], type=float, default=None,
+            help="Per-call timeout seconds.",
+        ),
+        click.Option(
+            ["--log-level", "linc_log_level"], default=None, help="LINC_LOG_LEVEL override.",
+        ),
+    ]
+    group.params.extend(global_options)
+
+    # The invocation's resolved mode, kept past the context's teardown so an exception that
+    # escapes to main() below is rendered the way the caller asked (--human vs JSON).
+    invocation: dict[str, str | None] = {"mode": None}
+
+    original_callback = group.callback
+
+    def callback(**kwargs: Any) -> Any:
+        ctx = click.get_current_context()
+        ctx.meta[_META + "mode"] = resolve_mode(kwargs.pop("linc_mode", None))
+        invocation["mode"] = ctx.meta[_META + "mode"]
+        ctx.meta[_META + "output"] = kwargs.pop("linc_output", None)
+        ctx.meta[_META + "timeout"] = kwargs.pop("linc_timeout", None)
+        configure_stderr_logging(kwargs.pop("linc_log_level", None))
+        harden_streams()
+        return original_callback(**kwargs) if original_callback else None
+
+    if original_callback is not None:
+        callback = functools.wraps(original_callback)(callback)
+    group.callback = callback
+
+    original_main = group.main
+
+    def main(*args: Any, **kwargs: Any) -> Any:
+        # Hard-assigned, not setdefault: a caller passing standalone_mode=True (e.g. a
+        # CliRunner.invoke(..., standalone_mode=True) test) must not be able to bypass the
+        # envelope contract (ruled fix, finding 2).
+        kwargs["standalone_mode"] = False
+        invocation["mode"] = None
+        try:
+            rv = original_main(*args, **kwargs)
+        except click.UsageError as exc:
+            emit_exception(UsageError(exc.format_message()), mode=_mode())
+            sys.exit(2)
+        except click.exceptions.Exit as exc:
+            sys.exit(exc.exit_code)
+        except click.exceptions.Abort as exc:
+            # Click converts KeyboardInterrupt (our SIGINT handler) into Abort.
+            interrupted = isinstance(exc.__cause__ or exc.__context__, KeyboardInterrupt)
+            err = ToolError(
+                "interrupted" if interrupted else "aborted",
+                code="INTERRUPTED" if interrupted else "ABORTED",
+            )
+            emit_exception(err, mode=_mode())
+            sys.exit(130 if interrupted else 1)
+        except Exception as exc:
+            # A hand-written override or group callback that raises must still honour the
+            # contract: envelope on stderr, empty stdout, no traceback. Generated commands
+            # already catch inside their callback; this is the net for everything else.
+            # SystemExit (e.g. our SIGTERM handler) is a BaseException and passes through.
+            sys.exit(emit_exception(exc, mode=_mode()))
+        else:
+            # type(rv) is int, not isinstance: bool is an int subclass, and a callback that
+            # happens to return True/False must not be mistaken for an exit code (minor 7).
+            sys.exit(rv if type(rv) is int else 0)
+
+    def _mode() -> str:
+        return invocation["mode"] or resolve_mode(None)
+
+    group.main = main
+    return group
+
+
+def _example_line(description: str) -> str | None:
+    for line in description.splitlines():
+        idx = line.find("Example:")
+        if idx != -1:
+            return line[idx:].strip()
+    return None
+
+
+def _build_command(
+    spec: ToolSpec, name: str, transport: Transport, renderer: Callable[[Any], str] | None
+) -> click.Command:
+    options = options_for(spec.parameters)  # never mutates spec.parameters (ruling 9)
+    options.sort(key=lambda o: not o.required)  # required before optional
+
+    def callback(**kwargs: Any) -> None:
+        ctx = click.get_current_context()
+        payload = {k: v for k, v in kwargs.items() if v is not None and v != ()}
+        mode = current_mode()
+        try:
+            with heartbeat(label=name, mode=mode):
+                result = transport.call(spec, payload, timeout=current_timeout())
+            # emit() runs INSIDE the try (finding 1): a renderer (--human) or a mid-stream
+            # generator (--stream) that raises must still produce an envelope, not a bare
+            # traceback with empty stdout/stderr.
+            ctx.exit(
+                emit(result, mode=mode, output_path=current_output(), renderer=renderer,
+                     tool=name)
+            )
+        except click.exceptions.Exit:
+            # ctx.exit() above raises this on the success path — it is not an error to wrap.
+            raise
+        except click.UsageError as exc:  # narrowed from ClickException (minor 8): a
+            # click.FileError etc. is not a usage error and should fall through below.
+            ctx.exit(emit_exception(UsageError(exc.format_message()), mode=mode))
+        except Exception as exc:  # contract: never a raw traceback on stdout
+            ctx.exit(emit_exception(exc, mode=mode))
+
+    example = _example_line(spec.description)
+    help_text = spec.description.split("\n\n")[0]
+    cmd = click.Command(
+        name, params=list(options), callback=callback, help=help_text, epilog=example,
+    )
+    cmd.linc_transport = transport  # ruling 7
+    # Marks the command as kit-generated. The conformance suite classifies on THIS attribute,
+    # not on callback.__module__ — an adopter is free to wrap or replace the callback.
+    cmd.linc_kit_generated = True
+    return cmd
+
+
+def _normalized_type(ptype: click.ParamType) -> str:
+    return _TYPE_NAMES.get(ptype.name, ptype.name.upper())
+
+
+def _opt_doc(o: click.Parameter) -> dict[str, Any]:
+    choices = list(o.type.choices) if isinstance(o.type, click.Choice) else None
+    default = o.default
+    if default == () or default is getattr(click.core, "UNSET", object()):
+        default = None
+    return {
+        "flag": (o.opts or [o.name])[0],
+        "type": _normalized_type(o.type),
+        "required": bool(o.required),
+        "default": default,
+        "choices": choices,
+        "help": (getattr(o, "help", "") or ""),
+    }
+
+
+def _schema_command(group: click.Group) -> click.Command:
+    @click.command("schema", help="Emit the whole command tree as JSON (no --help crawl).")
+    @click.option("--json", "as_json", is_flag=True, default=True, help="Always JSON.")
+    def schema(as_json: bool) -> None:
+        ctx = click.get_current_context(silent=True)
+        root_name = ctx.find_root().info_name if ctx is not None else None
+        doc = {
+            "name": root_name or group.name,
+            "globals": {
+                (o.opts or [o.name])[0]: (o.help or "")
+                for o in group.params
+                if isinstance(o, click.Option)
+            },
+            "commands": {
+                cname: {
+                    "help": (cmd.help or "").split("\n")[0],
+                    "options": {
+                        p.name: _opt_doc(p) for p in cmd.params if isinstance(p, click.Option)
+                    },
+                }
+                for cname, cmd in sorted(group.commands.items())
+            },
+        }
+        click.echo(to_json(doc))
+
+    schema.linc_kit_generated = True  # marks "ours" so a re-mount on the same group won't collide
+    return schema
+
+
+def mount_tools(
+    group: click.Group,
+    server: Any,
+    *,
+    prefix: str = "",
+    transport: Transport | None = None,
+    skip: dict[str, str] | None = None,
+    renderers: dict[str, Callable[[Any], str]] | None = None,
+) -> list[str]:
+    """Reflect every registered tool into `group`. Hand-written commands win on name collision.
+
+    Daemon-only marking is NOT a `mount_tools` concern (finding 3, spec §5.4) — it belongs to
+    the `HttpDaemonTransport` a caller passes in via `transport=`, which already implements it.
+    """
+    if not any(getattr(p, "name", None) == "linc_mode" for p in group.params):
+        raise RuntimeError("call install_globals(group) before mount_tools")
+    transport = transport or LocalTransport()
+    skip = skip or {}
+    renderers = renderers or {}
+    existing_schema = group.commands.get("schema")
+    if existing_schema is not None and not getattr(existing_schema, "linc_kit_generated", False):
+        raise ValueError("group already defines 'schema'; the kit reserves that command name")
+    for tool_name, why in skip.items():
+        if not why.strip():
+            raise ValueError(f"skip['{tool_name}'] needs a justification string")
+    specs = registry_of(server)
+    unknown_skips = sorted(set(skip) - {spec.name for spec in specs})
+    if unknown_skips:
+        raise ValueError(f"skip references unknown tool(s): {unknown_skips}")
+    mounted: list[str] = []
+    for spec in specs:
+        if spec.name in skip:
+            continue
+        name = cli_name(spec.name, prefix)
+        if name in group.commands:
+            continue
+        group.add_command(_build_command(spec, name, transport, renderers.get(name)), name)
+        mounted.append(name)
+    group.add_command(_schema_command(group), "schema")
+    group.linc_transport = transport  # ruling 7
+    return mounted