oed-cli 0.1.0__py3-none-any.whl

oed_cli/__init__.py

@@ -0,0 +1,6 @@
+"""oed-cli — openEuler Infra command line, auto-discovered, AI-friendly."""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+__all__ = ["__version__"]

oed_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m oed_cli`` as an alias for the ``oed`` command."""
+
+from oed_cli.main import main
+
+if __name__ == "__main__":
+    main()

oed_cli/cli.py

@@ -0,0 +1,278 @@
+"""Click command surface for ``oed``.
+
+Reserved (built-in) commands:
+    oed --version
+    oed info
+    oed services
+    oed schema <service>[.<method>]
+    oed cache {show,clear,refresh}
+
+Dynamic dispatch (``oed <service> <method> ...``) lives in :mod:`oed_cli.main`
+and is documented in ``docs/cli-design.md`` (v0.2).
+
+``oed --help`` additionally lists every auto-discovered service so newcomers
+can see what the CLI exposes without reading docs first.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import sys
+from typing import Any
+
+import click
+
+from . import __version__
+from .discovery import (
+    CACHE_TTL_SECONDS,
+    DiscoveryFeed,
+    ServiceMeta,
+    current_community,
+    fetch_discovery,
+    fetch_spec,
+)
+from .errors import OedError
+from .http import DEFAULT_GATEWAY
+
+
+def _print_json(data: Any, *, error: bool = False) -> None:
+    click.echo(json.dumps(data, ensure_ascii=False, indent=2), err=error, color=False)
+
+
+def _resolve_feed(*, force_refresh: bool) -> DiscoveryFeed:
+    try:
+        return fetch_discovery(community=None, force_refresh=force_refresh)
+    except OedError as exc:
+        _print_json(exc.to_dict(), error=True)
+        sys.exit(exc.code)
+
+
+class OedCli(click.Group):
+    """Click group that decorates ``--help`` with the live discovery feed.
+
+    Falls back gracefully if the gateway is unreachable / the cache is empty:
+    no extra section in that case, the standard help still renders.
+    """
+
+    def get_help(self, ctx: click.Context) -> str:
+        original = super().get_help(ctx)
+        extra = self._services_help_section()
+        return f"{original}\n\n{extra}" if extra else original
+
+    @staticmethod
+    def _services_help_section() -> str | None:
+        try:
+            feed = fetch_discovery()
+        except Exception:
+            return None
+        community = current_community()
+        services = feed.for_community(community)
+        if not services:
+            return None
+
+        widths = {"name": max(len(s.service_name) for s in services)}
+        rows: list[str] = []
+        for s in services:
+            desc = (s.description or s.title or "").strip().split("\n", 1)[0]
+            if len(desc) > 78:
+                desc = desc[:75] + "..."
+            rows.append(f"  {s.service_name.ljust(widths['name'])}    {desc}")
+
+        first = services[0].service_name
+        title = (
+            f"Auto-discovered services (community='{community}', "
+            f"{len(services)} service{'' if len(services) == 1 else 's'} "
+            f"resolved live from the gateway):"
+        )
+        return (
+            f"{title}\n\n"
+            + "\n".join(rows)
+            + "\n\n"
+            "Every declared query / path parameter on an operation is exposed\n"
+            "as its own --<kebab-case> flag. Use `oed <service> --help` to list\n"
+            "operations, then `oed <service> <operation> --help` to see the\n"
+            "flags for that operation. For the full spec: `oed schema <service>`.\n"
+            "\n"
+            "Quickstart:\n"
+            f"  oed {first}                            # list operations\n"
+            f"  oed cve getSecurityNoticeByCveId --cve-id CVE-2019-10082\n"
+            f"  oed meeting listMeetings --date 2026-07-29\n"
+        )
+
+
+def _format_service(service: ServiceMeta, *, age_s: float | None) -> dict[str, Any]:
+    out: dict[str, Any] = {
+        "name": service.name,
+        "service_name": service.service_name,
+        "community": service.community,
+        "title": service.title,
+        "version": service.version,
+    }
+    if service.description:
+        out["description"] = service.description
+    if service.base_url:
+        out["base_url"] = service.base_url
+    if age_s is not None:
+        out["fetched_seconds_ago"] = round(age_s, 1)
+    return out
+
+
+@click.group(
+    cls=OedCli,
+    context_settings={"help_option_names": ["-h", "--help"]},
+    invoke_without_command=True,
+)
+@click.version_option(version=__version__, prog_name="oed")
+@click.option(
+    "--no-color",
+    is_flag=True,
+    default=True,
+    help="Disable ANSI colors in output (default: true, AI-friendly).",
+)
+@click.pass_context
+def cli(ctx: click.Context, no_color: bool) -> None:
+    """oed — openEuler Infra command line. Auto-discovered, AI-friendly."""
+    ctx.ensure_object(dict)
+    ctx.obj["no_color"] = no_color
+
+
+@cli.command("info")
+def info() -> None:
+    """Show gateway reachability and the discovery snapshot summary."""
+    import time
+
+    feed = _resolve_feed(force_refresh=False)
+    age = time.time() - feed.fetched_at
+
+    services = feed.services
+    payload = {
+        "ok": True,
+        "oed_version": __version__,
+        "gateway": DEFAULT_GATEWAY,
+        "community": current_community(),
+        "services_total": len(services),
+        "communities_seen": sorted({s.community for s in services}),
+        "cache": {
+            "ttl_seconds": CACHE_TTL_SECONDS,
+            "stale": age >= CACHE_TTL_SECONDS,
+            "fetched_seconds_ago": round(age, 1),
+            "fetched_at_iso": dt.datetime.fromtimestamp(
+                feed.fetched_at, tz=dt.timezone.utc
+            ).isoformat(),
+        },
+    }
+    _print_json(payload)
+
+
+@cli.command("services")
+@click.option("--community", default=None, help="Limit to one community (default: current).")
+@click.option("--refresh", is_flag=True, help="Force re-fetch the discovery feed first.")
+def services_cmd(community: str | None, refresh: bool) -> None:
+    """List services in the discovery feed."""
+    import time
+
+    feed = _resolve_feed(force_refresh=refresh)
+    target = community or current_community()
+    items = [s for s in feed.services if s.community == target]
+    age = time.time() - feed.fetched_at
+    _print_json([_format_service(s, age_s=age) for s in items])
+
+
+@cli.command("schema")
+@click.argument("target")
+@click.option("--refresh", is_flag=True, help="Force re-fetch the discovery feed first.")
+def schema_cmd(target: str, refresh: bool) -> None:
+    """Print OpenAPI 3.x spec for SERVICE[.METHOD] from the current community."""
+    if "." in target:
+        service_name, method = target.split(".", 1)
+    else:
+        service_name, method = target, None
+
+    feed = _resolve_feed(force_refresh=refresh)
+    community = current_community()
+    try:
+        service = feed.find_service(community, service_name)
+    except OedError as exc:
+        _print_json(exc.to_dict(), error=True)
+        sys.exit(exc.code)
+
+    try:
+        spec = fetch_spec(service)
+    except OedError as exc:
+        _print_json(exc.to_dict(), error=True)
+        sys.exit(exc.code)
+
+    if method is None:
+        _print_json(spec)
+        return
+
+    paths: dict[str, Any] = spec.get("paths", {})
+    matches: list[dict[str, Any]] = []
+    for path, item in paths.items():
+        for verb, op in item.items():
+            if verb.lower() not in {"get", "post", "put", "patch", "delete", "head", "options"}:
+                continue
+            if op.get("operationId") == method or method in (path, f"{verb.upper()} {path}"):
+                matches.append({"path": path, "method": verb.upper(), "operation": op})
+    if not matches:
+        _print_json(
+            {
+                "ok": False,
+                "code": 4,
+                "error": "method_not_found",
+                "message": f"no path matches method '{method}' on service '{service_name}'",
+                "available_paths": sorted(paths.keys()),
+            },
+            error=True,
+        )
+        sys.exit(4)
+
+    _print_json({"service": service.name, "matches": matches})
+
+
+@cli.group()
+def cache() -> None:
+    """Manage the local discovery cache."""
+
+
+@cache.command("show")
+def cache_show() -> None:
+    from .discovery import _cache_path
+
+    p = _cache_path()
+    if not p.is_file():
+        _print_json({"cached": False, "path": str(p)})
+        return
+    stat = p.stat()
+    _print_json(
+        {
+            "cached": True,
+            "path": str(p),
+            "size_bytes": stat.st_size,
+            "modified_iso": dt.datetime.fromtimestamp(
+                stat.st_mtime, tz=dt.timezone.utc
+            ).isoformat(),
+            "ttl_seconds": CACHE_TTL_SECONDS,
+        }
+    )
+
+
+@cache.command("clear")
+def cache_clear() -> None:
+    from .discovery import _cache_path
+
+    p = _cache_path()
+    if p.is_file():
+        p.unlink()
+    _print_json({"ok": True, "cleared": str(p)})
+
+
+@cache.command("refresh")
+def cache_refresh() -> None:
+    feed = fetch_discovery(community=None, force_refresh=True)
+    _print_json({"ok": True, "services_total": len(feed.services)})
+
+
+if __name__ == "__main__":
+    cli()

oed_cli/discovery.py

@@ -0,0 +1,168 @@
+"""Discovery feed retrieval, parsing and local caching.
+
+Reads ``https://api-gateway.osinfra.cn/discovery/apis`` (per ``context/discoverAPI.md``)
+and caches the parsed feed under ``~/.cache/oed-cli/discovery.json``. A fresh
+fetch happens only when the cache is older than :data:`CACHE_TTL_SECONDS`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .errors import NotFoundError
+from .http import DEFAULT_GATEWAY, get_json
+
+CACHE_TTL_SECONDS = 600  # 10 minutes
+DEFAULT_COMMUNITY = "openeuler"
+APIS_URL = f"{DEFAULT_GATEWAY}/discovery/apis"
+SPEC_URL_TEMPLATE = f"{DEFAULT_GATEWAY}/discovery/apis/{{community}}/{{service_name}}"
+
+
+@dataclass(frozen=True)
+class ServiceMeta:
+    name: str
+    service_name: str
+    community: str
+    title: str
+    version: str
+    description: str
+    base_url: str
+
+    @classmethod
+    def from_raw(cls, raw: dict[str, Any]) -> ServiceMeta:
+        return cls(
+            name=raw["name"],
+            service_name=raw["service_name"],
+            community=raw["community"],
+            title=raw.get("title", ""),
+            version=raw.get("version", ""),
+            description=raw.get("description", ""),
+            base_url=raw.get("base_url", ""),
+        )
+
+
+@dataclass
+class DiscoveryFeed:
+    fetched_at: float
+    raw: dict[str, Any]
+    services: list[ServiceMeta] = field(default_factory=list)
+
+    def for_community(self, community: str) -> list[ServiceMeta]:
+        return [s for s in self.services if s.community == community]
+
+    def find_service(self, community: str, service_name: str) -> ServiceMeta:
+        for s in self.services:
+            if s.community == community and s.service_name == service_name:
+                return s
+        raise NotFoundError(
+            f"service '{service_name}' not found in community '{community}'",
+            kind="service_not_found",
+            hint="Run `oed services` to see the registered services.",
+        )
+
+
+def _cache_dir() -> Path:
+    override = os.environ.get("OED_CACHE_DIR")
+    if override:
+        return Path(override).expanduser()
+    if platform.system() == "Windows":
+        base = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
+        return base / "oed-cli" / "cache"
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".cache"
+    return base / "oed-cli"
+
+
+def _cache_path() -> Path:
+    return _cache_dir() / "discovery.json"
+
+
+def _read_cache(path: Path) -> DiscoveryFeed | None:
+    if not path.is_file():
+        return None
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return _materialize(raw)
+
+
+def _materialize(raw: dict[str, Any]) -> DiscoveryFeed:
+    fetched_at = float(raw.get("__oed_fetched_at", 0))
+    services = [ServiceMeta.from_raw(s) for s in raw.get("services", [])]
+    return DiscoveryFeed(fetched_at=fetched_at, raw=raw, services=services)
+
+
+def _write_cache(path: Path, feed: DiscoveryFeed) -> None:
+    payload = {
+        "__oed_fetched_at": feed.fetched_at,
+        "services": [s.__dict__ for s in feed.services],
+    }
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    except OSError:
+        # Cache is best-effort; failures here are not fatal.
+        pass
+
+
+def _fetch_remote(community: str | None) -> DiscoveryFeed:
+    """Hit the gateway. If ``community`` is provided, request that variant so the
+    payload layout matches the per-community view; otherwise request the global
+    payload which is keyed by community."""
+
+    if community:
+        data = get_json(APIS_URL, params={"community": community})
+        services: list[ServiceMeta] = []
+        if isinstance(data, list):
+            services = [ServiceMeta.from_raw(s) for s in data]
+    else:
+        data = get_json(APIS_URL)
+        services = []
+        communities = data.get("communities", {}) if isinstance(data, dict) else {}
+        if isinstance(communities, dict):
+            for arr in communities.values():
+                if isinstance(arr, list):
+                    services.extend(ServiceMeta.from_raw(s) for s in arr)
+
+    raw_payload = data if isinstance(data, dict) else {"services": data}
+    return DiscoveryFeed(
+        fetched_at=time.time(), raw=raw_payload, services=services
+    )
+
+
+def fetch_discovery(*, community: str | None = None, force_refresh: bool = False) -> DiscoveryFeed:
+    """Return the discovery feed, using cache when fresh."""
+
+    cache_file = _cache_path()
+    cached = None if force_refresh else _read_cache(cache_file)
+    if cached is not None and (time.time() - cached.fetched_at) < CACHE_TTL_SECONDS:
+        return cached
+
+    feed = _fetch_remote(community)
+    _write_cache(cache_file, feed)
+    return feed
+
+
+def fetch_spec(service: ServiceMeta) -> dict[str, Any]:
+    """Return the OpenAPI 3.x spec for one service, parsed JSON."""
+
+    url = SPEC_URL_TEMPLATE.format(community=service.community, service_name=service.service_name)
+    data = get_json(url)
+    if not isinstance(data, dict) or "openapi" not in data:
+        raise NotFoundError(
+            f"spec at {url} did not return an OpenAPI document",
+            kind="spec_not_found",
+            hint="The registered service may be missing its openapi.yaml upstream.",
+        )
+    return data
+
+
+def current_community() -> str:
+    return os.environ.get("OED_COMMUNITY", DEFAULT_COMMUNITY)