eightstatecli 0.4.0__py3-none-any.whl

escli/services/describe.py

@@ -0,0 +1,186 @@
+"""
+CLI self-description system — generates machine-readable manifests
+from argparse parsers for agent discovery.
+
+Agents call `escli --describe` to get a compact JSON manifest of all
+commands, or `escli <command> --schema` for per-command detail.
+
+Token budget: --describe returns ~300-500 tokens (compact index).
+Per-command --schema returns ~100-200 tokens (full detail for one command).
+"""
+
+import argparse
+import json
+from typing import Any
+
+from escli import __version__
+
+
+def generate_manifest(parser: argparse.ArgumentParser) -> dict:
+    """Generate the compact CLI manifest for --describe."""
+    commands = []
+    # Walk the subparsers
+    for action in parser._subparsers._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            # Build a help text lookup from choices_actions
+            help_map: dict[str, str] = {}
+            for choice_action in getattr(action, '_choices_actions', []):
+                help_map[choice_action.dest] = choice_action.help or ""
+
+            for name, subparser in action.choices.items():
+                if _is_alias(name, action):
+                    continue
+                cmd = _describe_command(name, subparser, help_map.get(name, ""))
+                if cmd:
+                    commands.append(cmd)
+
+    return {
+        "name": "escli",
+        "version": __version__,
+        "description": "Eightstate CLI — AI services from the command line",
+        "agent_instructions": {
+            "structured_output": "Use --json for all commands to get {ok, data, error, meta} envelope on stdout",
+            "quiet_mode": "Use --quiet to suppress stderr progress messages",
+            "auth": "Run 'escli auth login' for browser OAuth, or set service-specific env vars",
+            "exit_codes": {
+                "0": "success",
+                "1": "error",
+                "2": "usage/validation",
+                "4": "auth failure",
+                "5": "not found",
+                "8": "transient/retryable",
+            },
+        },
+        "commands": commands,
+    }
+
+
+def generate_command_schema(name: str, parser: argparse.ArgumentParser) -> dict | None:
+    """Generate detailed schema for a single command (--schema flag)."""
+    # Find the subparser for this command
+    for action in parser._subparsers._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            if name in action.choices:
+                subparser = action.choices[name]
+                return _describe_command_detail(name, subparser)
+    return None
+
+
+def _is_alias(name: str, action: argparse._SubParsersAction) -> bool:
+    """Check if a subparser name is an alias (shares parser with another name)."""
+    parser = action.choices[name]
+    for other_name, other_parser in action.choices.items():
+        if other_parser is parser and other_name != name and len(other_name) > len(name):
+            return True  # This name is shorter = alias
+    return False
+
+
+def _describe_command(name: str, parser: argparse.ArgumentParser, help_text: str = "") -> dict | None:
+    """Generate compact command entry for the manifest."""
+    desc = help_text or _first_line(parser.description or "") or name
+
+    # Check for subcommands
+    subcommands = []
+    for action in parser._subparsers._actions if parser._subparsers else []:
+        if isinstance(action, argparse._SubParsersAction):
+            for sub_name, sub_parser in action.choices.items():
+                if not _is_alias(sub_name, action):
+                    subcommands.append(sub_name)
+
+    entry: dict[str, Any] = {
+        "name": name,
+        "description": desc,
+    }
+    if subcommands:
+        entry["subcommands"] = subcommands
+    return entry
+
+
+def _describe_command_detail(name: str, parser: argparse.ArgumentParser) -> dict:
+    """Generate full command schema with args, flags, examples."""
+    args = []
+    flags = []
+
+    for action in parser._actions:
+        if isinstance(action, (argparse._HelpAction, argparse._VersionAction)):
+            continue
+        if isinstance(action, argparse._SubParsersAction):
+            continue
+
+        if action.option_strings:
+            # It's a flag
+            flag: dict[str, Any] = {
+                "names": action.option_strings,
+                "type": _type_name(action),
+                "required": action.required,
+            }
+            if action.default is not None and action.default != argparse.SUPPRESS:
+                flag["default"] = str(action.default) if action.default is not argparse.SUPPRESS else None
+            if action.help and action.help != argparse.SUPPRESS:
+                flag["description"] = action.help
+            if action.choices:
+                flag["choices"] = list(action.choices)
+            flags.append(flag)
+        else:
+            # Positional argument
+            arg: dict[str, Any] = {
+                "name": action.dest,
+                "type": _type_name(action),
+                "required": action.nargs not in ('?', '*'),
+            }
+            if action.help and action.help != argparse.SUPPRESS:
+                arg["description"] = action.help
+            if action.nargs in ('+', '*'):
+                arg["multiple"] = True
+            args.append(arg)
+
+    result: dict[str, Any] = {
+        "command": name,
+        "description": _first_line(parser.description or ""),
+    }
+    if args:
+        result["arguments"] = args
+    if flags:
+        result["flags"] = flags
+
+    # Extract examples from epilog
+    if parser.epilog:
+        examples = _extract_examples(parser.epilog)
+        if examples:
+            result["examples"] = examples
+
+    return result
+
+
+def _type_name(action: argparse.Action) -> str:
+    """Get a human/machine-readable type name for an action."""
+    if isinstance(action, (argparse._StoreTrueAction, argparse._StoreFalseAction)):
+        return "bool"
+    if action.type is int:
+        return "int"
+    if action.type is float:
+        return "float"
+    if action.choices:
+        return "enum"
+    if action.nargs in ('+', '*'):
+        return "string[]"
+    return "string"
+
+
+def _first_line(text: str) -> str:
+    """Get the first non-empty line of text."""
+    for line in text.strip().split('\n'):
+        line = line.strip()
+        if line:
+            return line
+    return ""
+
+
+def _extract_examples(epilog: str) -> list[str]:
+    """Extract example commands from epilog text."""
+    examples = []
+    for line in epilog.split('\n'):
+        line = line.strip()
+        if line.startswith('escli '):
+            examples.append(line)
+    return examples[:5]  # Cap at 5 examples

escli/services/output.py

@@ -0,0 +1,168 @@
+"""
+Structured output envelope and error types for agent consumption.
+
+Every --json response uses the standard envelope:
+  {"ok": true,  "data": {...}, "error": null, "meta": {...}}
+  {"ok": false, "data": null,  "error": {...}, "meta": {...}}
+
+Error objects include machine-readable codes and remediation hints.
+"""
+
+import json as jsonlib
+import sys
+import time
+from typing import Any
+
+
+class CliError(Exception):
+    """Structured CLI error with code, category, and remediation."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        category: str = "user",  # user, system, transient
+        exit_code: int = 1,
+        retryable: bool = False,
+        remediation: list[dict] | None = None,
+        details: dict | None = None,
+    ):
+        super().__init__(message)
+        self.code = code
+        self.category = category
+        self.exit_code = exit_code
+        self.retryable = retryable
+        self.remediation = remediation or []
+        self.details = details
+
+    def to_dict(self) -> dict:
+        d: dict = {
+            "code": self.code,
+            "category": self.category,
+            "message": str(self),
+            "retryable": self.retryable,
+        }
+        if self.remediation:
+            d["remediation"] = self.remediation
+        if self.details:
+            d["details"] = self.details
+        return d
+
+
+# ── Common errors ────────────────────────────────────────────────
+
+class AuthError(CliError):
+    def __init__(self, message: str = "not authenticated", **kwargs):
+        super().__init__(
+            code="cli.auth.required",
+            message=message,
+            category="user",
+            exit_code=4,
+            remediation=[{"action": "run", "command": "escli auth login"}],
+            **kwargs,
+        )
+
+
+class NotFoundError(CliError):
+    def __init__(self, resource: str, **kwargs):
+        super().__init__(
+            code="cli.not_found",
+            message=f"not found: {resource}",
+            category="user",
+            exit_code=5,
+            **kwargs,
+        )
+
+
+class ValidationError(CliError):
+    def __init__(self, message: str, **kwargs):
+        super().__init__(
+            code="cli.validation",
+            message=message,
+            category="user",
+            exit_code=2,
+            **kwargs,
+        )
+
+
+class TransientError(CliError):
+    def __init__(self, message: str, retry_after: int | None = None, **kwargs):
+        remediation = [{"action": "retry"}]
+        if retry_after:
+            remediation[0]["backoff_seconds"] = retry_after
+        super().__init__(
+            code="cli.transient",
+            message=message,
+            category="transient",
+            exit_code=8,
+            retryable=True,
+            remediation=remediation,
+            **kwargs,
+        )
+
+
+class ApiError(CliError):
+    def __init__(self, status: int, message: str, **kwargs):
+        retryable = status in (429, 500, 502, 503, 504)
+        category = "transient" if retryable else "system"
+        code = {
+            401: "cli.auth.invalid",
+            403: "cli.auth.forbidden",
+            404: "cli.not_found",
+            429: "cli.rate_limited",
+        }.get(status, f"cli.api.{status}")
+
+        remediation = []
+        if status == 401:
+            remediation = [{"action": "run", "command": "escli auth login"}]
+        elif status == 429:
+            remediation = [{"action": "retry", "backoff_seconds": 30}]
+        elif status >= 500:
+            remediation = [{"action": "retry", "backoff_seconds": 5}]
+
+        super().__init__(
+            code=code,
+            message=message,
+            category=category,
+            exit_code=8 if retryable else 1,
+            retryable=retryable,
+            remediation=remediation,
+            **kwargs,
+        )
+
+
+# ── Envelope ─────────────────────────────────────────────────────
+
+def success(data: Any = None, meta: dict | None = None) -> dict:
+    """Build a success envelope."""
+    return {"ok": True, "data": data, "error": None, "meta": meta or {}}
+
+
+def failure(error: CliError | dict | str, meta: dict | None = None) -> dict:
+    """Build a failure envelope."""
+    if isinstance(error, CliError):
+        err = error.to_dict()
+    elif isinstance(error, dict):
+        err = error
+    else:
+        err = {"code": "cli.error", "category": "system", "message": str(error), "retryable": False}
+    return {"ok": False, "data": None, "error": err, "meta": meta or {}}
+
+
+def emit_json(envelope: dict):
+    """Print a JSON envelope to stdout."""
+    print(jsonlib.dumps(envelope))
+
+
+def emit_error(error: CliError, use_json: bool = False) -> int:
+    """Print an error and return the exit code."""
+    if use_json:
+        emit_json(failure(error))
+    else:
+        print(f"  ✗ {error}", file=sys.stderr)
+        for r in error.remediation:
+            if r.get("command"):
+                print(f"  → run: {r['command']}", file=sys.stderr)
+            elif r.get("hint"):
+                print(f"  → {r['hint']}", file=sys.stderr)
+    return error.exit_code