humancli 0.1.0__py3-none-any.whl

agentcli/_errors.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Iterable
+
+if TYPE_CHECKING:
+    from ._output import ErrorInfo
+
+
+@dataclass(frozen=True)
+class FieldError:
+    field: str
+    message: str
+
+
+class AgentCliError(Exception):
+    def __init__(
+        self,
+        *,
+        code: str,
+        message: str,
+        retryable: bool = False,
+        cta: list[str] | None = None,
+        exit_code: int = 1,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.retryable = retryable
+        self.cta = cta
+        self.exit_code = exit_code
+
+    def to_error_info(self) -> ErrorInfo:
+        from ._output import ErrorInfo
+
+        return ErrorInfo(
+            code=self.code,
+            message=self.message,
+            retryable=self.retryable,
+            cta=self.cta,
+        )
+
+
+class ParseError(AgentCliError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "PARSE",
+        retryable: bool = True,
+        cta: list[str] | None = None,
+    ) -> None:
+        super().__init__(
+            code=code,
+            message=message,
+            retryable=retryable,
+            cta=cta,
+            exit_code=1,
+        )
+
+
+class ValidationError(AgentCliError):
+    def __init__(
+        self,
+        *,
+        message: str,
+        field_errors: list[FieldError] | None = None,
+        cta: list[str] | None = None,
+    ) -> None:
+        super().__init__(
+            code="VALIDATION",
+            message=message,
+            retryable=True,
+            cta=cta,
+            exit_code=1,
+        )
+        self.field_errors = field_errors or []
+
+
+class ConfigError(AgentCliError):
+    def __init__(self, message: str) -> None:
+        super().__init__(
+            code="CONFIG",
+            message=message,
+            retryable=False,
+            exit_code=1,
+        )
+
+
+def levenshtein(left: str, right: str) -> int:
+    if left == right:
+        return 0
+    if not left:
+        return len(right)
+    if not right:
+        return len(left)
+    previous = list(range(len(right) + 1))
+    for i, left_char in enumerate(left, start=1):
+        current = [i]
+        for j, right_char in enumerate(right, start=1):
+            current.append(
+                min(
+                    current[j - 1] + 1,
+                    previous[j] + 1,
+                    previous[j - 1] + (left_char != right_char),
+                )
+            )
+        previous = current
+    return previous[-1]
+
+
+def suggest_matches(
+    value: str,
+    choices: Iterable[str],
+    *,
+    threshold: int = 2,
+    limit: int = 3,
+) -> list[str]:
+    scored: list[tuple[int, str]] = []
+    lowered = value.lower()
+    for choice in choices:
+        distance = levenshtein(lowered, choice.lower())
+        if distance <= threshold:
+            scored.append((distance, choice))
+    scored.sort(key=lambda item: (item[0], item[1]))
+    return [choice for _, choice in scored[:limit]]
+
+
+def unknown_name_error(*, kind: str, value: str, choices: Iterable[str]) -> ParseError:
+    suggestions = suggest_matches(value, choices)
+    hint = f" Did you mean: {', '.join(suggestions)}?" if suggestions else ""
+    return ParseError(
+        f'Unknown {kind} "{value}".{hint}', code=f"UNKNOWN_{kind.upper()}"
+    )
+
+
+def normalize_exception(error: Exception) -> AgentCliError:
+    if isinstance(error, AgentCliError):
+        return error
+    return AgentCliError(code="UNKNOWN", message=str(error) or error.__class__.__name__)

agentcli/_help.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from ._types import CommandSchema, ParameterSpec
+
+
+def render_app_help(app, *, path: tuple[str, ...] = ()) -> str:
+    title = " ".join(path or (app.name,))
+    lines = [title]
+    if app.description:
+        lines.extend(["", app.description])
+    lines.extend(["", f"Usage: {title} <command>"])
+    if app.subapps:
+        lines.extend(["", "Groups:"])
+        for name, subapp in sorted(app.subapps.items()):
+            lines.append(f"  {name:<16} {(subapp.description or '')}".rstrip())
+    if app.commands:
+        lines.extend(["", "Commands:"])
+        for name, command in sorted(app.commands.items()):
+            lines.append(f"  {name:<16} {(command.description or '')}".rstrip())
+    return "\n".join(lines)
+
+
+def render_command_help(command: CommandSchema) -> str:
+    path = " ".join(command.path)
+    lines = [path]
+    if command.description:
+        lines.extend(["", command.description])
+    lines.extend(["", f"Usage: {path}{_usage(command)}"])
+    if command.positionals:
+        lines.extend(["", "Arguments:"])
+        lines.extend(_parameters(command.positionals))
+    visible_options = [
+        parameter for parameter in command.options if not parameter.hidden
+    ]
+    if visible_options:
+        lines.extend(["", "Options:"])
+        lines.extend(_parameters(visible_options))
+    return "\n".join(lines)
+
+
+def _usage(command: CommandSchema) -> str:
+    parts = []
+    for parameter in command.positionals:
+        parts.append(
+            f"<{parameter.name}>" if parameter.required else f"[{parameter.name}]"
+        )
+    for parameter in command.options:
+        if parameter.hidden:
+            continue
+        parts.append(
+            f"[--{parameter.cli_name}]"
+            if parameter.is_bool
+            else f"[--{parameter.cli_name} VALUE]"
+        )
+    return (" " + " ".join(parts)) if parts else ""
+
+
+def _parameters(parameters: list[ParameterSpec]) -> list[str]:
+    lines = []
+    for parameter in parameters:
+        label = parameter.display_name
+        if parameter.alias:
+            label = f"{label}, -{parameter.alias}"
+        lines.append(f"  {label:<24} {(parameter.description or '')}".rstrip())
+    return lines

agentcli/_output.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+import dataclasses
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from ._errors import AgentCliError
+
+
+@dataclass(frozen=True)
+class ErrorInfo:
+    code: str
+    message: str
+    retryable: bool = False
+    cta: list[str] | None = None
+
+
+@dataclass
+class Meta:
+    command: str
+    cta: list[str] | None = None
+    duration_ms: float | None = None
+    streamed: bool = False
+
+
+@dataclass(frozen=True)
+class Envelope:
+    ok: bool
+    data: Any | None = None
+    error: ErrorInfo | None = None
+    meta: Meta | None = None
+
+
+def make_success_envelope(
+    data: Any,
+    *,
+    command: str,
+    cta: list[str] | None = None,
+) -> Envelope:
+    return Envelope(ok=True, data=data, meta=Meta(command=command, cta=cta))
+
+
+def make_error_envelope(error: Exception, *, command: str) -> Envelope:
+    if isinstance(error, AgentCliError):
+        info = ErrorInfo(
+            code=error.code,
+            message=error.message,
+            retryable=error.retryable,
+            cta=error.cta,
+        )
+    else:
+        info = ErrorInfo(code="UNKNOWN", message=str(error), retryable=False)
+    return Envelope(ok=False, error=info, meta=Meta(command=command, cta=info.cta))
+
+
+def make_envelope(
+    *,
+    ok: bool,
+    command: str,
+    format: str,
+    data: Any = None,
+    error: ErrorInfo | None = None,
+    duration_ms: float | None = None,
+    cta: list[str] | None = None,
+    streamed: bool = False,
+) -> Envelope:
+    if ok:
+        return Envelope(
+            ok=True,
+            data=data,
+            meta=Meta(
+                command=command, cta=cta, duration_ms=duration_ms, streamed=streamed
+            ),
+        )
+    return Envelope(
+        ok=False,
+        error=error,
+        meta=Meta(command=command, cta=cta, duration_ms=duration_ms, streamed=streamed),
+    )
+
+
+def normalize_value(value: Any) -> Any:
+    if dataclasses.is_dataclass(value):
+        return normalize_value(dataclasses.asdict(value))
+    if hasattr(value, "to_dict") and callable(value.to_dict):
+        return normalize_value(value.to_dict())
+    if hasattr(value, "model_dump") and callable(value.model_dump):
+        return normalize_value(value.model_dump())
+    if isinstance(value, dict):
+        return {
+            str(key): normalize_value(item)
+            for key, item in value.items()
+            if item is not None
+        }
+    if isinstance(value, (list, tuple)):
+        return [normalize_value(item) for item in value]
+    return value
+
+
+def envelope_payload(envelope: Envelope, *, verbose: bool) -> Any:
+    if envelope.ok and not verbose:
+        return normalize_value(envelope.data)
+    return normalize_value(dataclasses.asdict(envelope))
+
+
+def render_output(
+    envelope: Envelope,
+    *,
+    format_name: str | None,
+    is_tty: bool,
+    verbose: bool = False,
+) -> str:
+    actual_format = format_name or ("pretty" if is_tty else "toon")
+    payload = envelope_payload(envelope, verbose=verbose)
+    if actual_format == "json":
+        return json.dumps(payload, indent=2, default=str)
+    if actual_format == "jsonl":
+        return json.dumps(payload, default=str)
+    if actual_format == "md":
+        return render_markdown(payload)
+    if actual_format == "yaml":
+        return render_yaml(payload)
+    if actual_format == "pretty":
+        return render_plain(payload)
+    return render_toon(payload)
+
+
+def render_stream_item(
+    item: Any,
+    *,
+    format_name: str | None = None,
+    output_format: str | None = None,
+    is_tty: bool | None = None,
+) -> str:
+    format_name = output_format or format_name
+    payload = normalize_value(item)
+    if format_name == "jsonl":
+        return json.dumps(payload, default=str)
+    if format_name == "json":
+        return json.dumps(payload, indent=2, default=str)
+    if format_name == "md":
+        return render_markdown(payload)
+    return render_toon(payload)
+
+
+def render_envelope(envelope: Envelope, *, format: str, verbose: bool = False) -> str:
+    return render_output(
+        envelope, format_name=format, is_tty=(format == "human"), verbose=verbose
+    )
+
+
+def render_plain(value: Any) -> str:
+    value = normalize_value(value)
+    if isinstance(value, dict):
+        return "\n".join(_plain_lines(value))
+    if isinstance(value, list):
+        return "\n".join(f"- {item}" for item in value)
+    return str(value)
+
+
+def _plain_lines(value: dict[str, Any], indent: int = 0) -> list[str]:
+    lines: list[str] = []
+    prefix = " " * indent
+    for key, item in value.items():
+        if isinstance(item, dict):
+            lines.append(f"{prefix}{key}:")
+            lines.extend(_plain_lines(item, indent + 2))
+            continue
+        if isinstance(item, list):
+            lines.append(f"{prefix}{key}:")
+            lines.extend(f"{prefix}  - {entry}" for entry in item)
+            continue
+        lines.append(f"{prefix}{key}: {item}")
+    return lines
+
+
+def render_toon(value: Any) -> str:
+    value = normalize_value(value)
+    if isinstance(value, dict):
+        return "\n".join(_toon_dict(value))
+    if isinstance(value, list):
+        return _toon_list("items", value)
+    return _toon_scalar(value)
+
+
+def _toon_dict(value: dict[str, Any], indent: int = 0) -> list[str]:
+    lines: list[str] = []
+    prefix = " " * indent
+    for key, item in value.items():
+        if item is None:
+            continue
+        if isinstance(item, dict):
+            if not item:
+                lines.append(f"{prefix}{key}: (empty)")
+                continue
+            lines.append(f"{prefix}{key}:")
+            lines.extend(_toon_dict(item, indent + 2))
+            continue
+        if isinstance(item, list):
+            lines.extend(_toon_list_lines(key, item, indent))
+            continue
+        lines.append(f"{prefix}{key}: {_toon_scalar(item)}")
+    return lines
+
+
+def _toon_list(key: str, value: list[Any]) -> str:
+    return "\n".join(_toon_list_lines(key, value, 0))
+
+
+def _toon_list_lines(key: str, value: list[Any], indent: int) -> list[str]:
+    prefix = " " * indent
+    if not value:
+        return [f"{prefix}{key}: (empty)"]
+    if all(not isinstance(item, (dict, list)) for item in value):
+        joined = ",".join(_toon_scalar(item) for item in value)
+        return [f"{prefix}{key}[{len(value)}]: {joined}"]
+    if all(isinstance(item, dict) and item for item in value):
+        headers = list(value[0].keys())
+        if all(list(item.keys()) == headers for item in value):
+            lines = [f"{prefix}{key}[{len(value)}]{{{','.join(headers)}}}:"]
+            for item in value:
+                row = ",".join(_toon_scalar(item[column]) for column in headers)
+                lines.append(f"{prefix}  {row}")
+            return lines
+    lines = [f"{prefix}{key}:"]
+    for item in value:
+        lines.append(f"{prefix}  - {_toon_scalar(item)}")
+    return lines
+
+
+def _toon_scalar(value: Any) -> str:
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if value is None:
+        return "(empty)"
+    if isinstance(value, (int, float)):
+        return str(value)
+    text = str(value)
+    if not text:
+        return '""'
+    if any(char in text for char in [":", ",", "\n", '"']):
+        return json.dumps(text)
+    return text
+
+
+def render_markdown(value: Any) -> str:
+    value = normalize_value(value)
+    if (
+        isinstance(value, list)
+        and value
+        and all(isinstance(item, dict) for item in value)
+    ):
+        headers = list(value[0].keys())
+        lines = [
+            f"| {' | '.join(headers)} |",
+            f"| {' | '.join('---' for _ in headers)} |",
+        ]
+        for item in value:
+            lines.append(
+                f"| {' | '.join(str(item.get(header, '')) for header in headers)} |"
+            )
+        return "\n".join(lines)
+    if isinstance(value, dict):
+        return "\n".join(f"- **{key}**: {item}" for key, item in value.items())
+    if isinstance(value, list):
+        return "\n".join(f"- {item}" for item in value)
+    return str(value)
+
+
+def render_yaml(value: Any) -> str:
+    try:
+        import yaml
+    except ImportError as exc:
+        raise AgentCliError(
+            code="MISSING_DEP",
+            message="YAML output requires agentcli[yaml]",
+            retryable=False,
+        ) from exc
+    return yaml.safe_dump(normalize_value(value), sort_keys=False)