current-cli 0.1.0__py3-none-any.whl

current_cli/__init__.py

@@ -0,0 +1 @@
+"""Command line interface for the Current API, generated from its OpenAPI schema."""

current_cli/build.py

@@ -0,0 +1,86 @@
+"""Turn OpenAPI operations into a nested tree of click commands."""
+
+from __future__ import annotations
+
+import click
+
+from . import config, http
+from .schema import Operation
+
+
+def _make_callback(op: Operation):
+    def callback(**kwargs):
+        data = kwargs.pop("data", None)
+
+        path = op.path
+        for param in op.path_params:
+            path = path.replace("{" + param.name + "}", str(kwargs.pop(param.name)))
+
+        params: dict[str, str] = {}
+        for param in op.query_params:
+            value = kwargs.pop(param.name, None)
+            if value is None and param.name == "workspace":
+                value = config.get("default_workspace")
+            if value is None:
+                if param.required:
+                    hint = (
+                        " (or set a default: current config set default_workspace <uuid>)"
+                        if param.name == "workspace"
+                        else ""
+                    )
+                    raise click.UsageError(f"Missing required option --{param.name}{hint}.")
+                continue
+            params[param.name] = value
+
+        json_body = http.parse_data_argument(data) if data is not None else None
+        response = http.request(op.method, path, params=params, json_body=json_body)
+        http.render_response(response)
+
+    return callback
+
+
+def _make_command(op: Operation) -> click.Command:
+    params: list[click.Parameter] = [click.Argument([param.name]) for param in op.path_params]
+    for param in op.query_params:
+        # Required query params are enforced in the callback so that
+        # `workspace` can fall back to the configured default.
+        params.append(
+            click.Option(
+                [f"--{param.name.replace('_', '-')}"],
+                required=False,
+                help=param.description or None,
+            )
+        )
+    if op.has_body:
+        params.append(
+            click.Option(
+                ["--data"],
+                required=op.method in ("post", "put", "patch"),
+                help="Request body as JSON: inline, @file.json, or - for stdin.",
+            )
+        )
+
+    help_text = f"{op.description}\n\n{op.method.upper()} {op.path}".strip()
+    return click.Command(
+        name=op.command,
+        params=params,
+        callback=_make_callback(op),
+        help=help_text,
+        short_help=op.description.split("\n")[0] if op.description else None,
+    )
+
+
+def add_operations(root: click.Group, operations: list[Operation]) -> None:
+    for op in operations:
+        group = root
+        for segment in op.group_path:
+            existing = group.commands.get(segment)
+            if existing is None:
+                existing = click.Group(name=segment, help=f"Operations under /{segment}/.")
+                group.add_command(existing)
+            elif not isinstance(existing, click.Group):
+                raise RuntimeError(
+                    f"Command tree conflict: {segment} is both a group and a command"
+                )
+            group = existing
+        group.add_command(_make_command(op))

current_cli/config.py

@@ -0,0 +1,54 @@
+"""Persistent CLI configuration (auth token, base URL, default workspace)."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+DEFAULT_BASE_URL = "http://localhost:8000"
+KNOWN_KEYS = ("base_url", "token", "email", "default_workspace")
+
+
+def config_dir() -> Path:
+    override = os.environ.get("CURRENT_CLI_CONFIG_DIR")
+    if override:
+        return Path(override)
+    return Path.home() / ".config" / "current-cli"
+
+
+def config_path() -> Path:
+    return config_dir() / "config.json"
+
+
+def load() -> dict:
+    path = config_path()
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text("utf-8"))
+
+
+def save(data: dict) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", "utf-8")
+
+
+def get(key: str) -> str | None:
+    return load().get(key)
+
+
+def set_value(key: str, value: str) -> None:
+    data = load()
+    data[key] = value
+    save(data)
+
+
+def unset(key: str) -> None:
+    data = load()
+    data.pop(key, None)
+    save(data)
+
+
+def base_url() -> str:
+    return os.environ.get("CURRENT_API_URL") or get("base_url") or DEFAULT_BASE_URL

current_cli/docs.py

@@ -0,0 +1,83 @@
+"""Render the full command tree as markdown, for LLMs and humans.
+
+The committed cli/llms.txt is generated from this module; a test fails if it
+is stale. Regenerate with: uv run python -m current_cli.docs > llms.txt
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+import click
+
+PREAMBLE = """\
+# Current CLI reference
+
+`current` is the command line interface for the Current API. Commands are
+generated from the API's OpenAPI schema, so every API operation is available.
+
+## Setup
+
+```bash
+pip install current-cli
+current config set base_url https://your-api.example.com   # default: http://localhost:8000
+current login you@example.com                              # magic-link sign in, stores the token
+current config set default_workspace <workspace-uuid>      # used when --workspace is omitted
+```
+
+The auth token is stored in `~/.config/current-cli/config.json` and sent as
+`Authorization: Token <token>`. `CURRENT_API_URL` overrides the base URL.
+
+## Conventions
+
+- Path parameters are positional arguments, shown below as `<name>`.
+- Query parameters are `--options`.
+- Request bodies are JSON, passed with `--data`: inline (`--data '{"name": "x"}'`),
+  from a file (`--data @body.json`), or from stdin (`--data -`).
+- Responses print as JSON on stdout. API errors print to stderr and exit 1.
+- `--schema <path-or-url>` (or `CURRENT_SCHEMA`) rebuilds the commands from a
+  different schema, for example `<base-url>/api/schema/` for a live server.
+- Every command supports `--help`.
+
+## Commands"""
+
+
+def _iter_commands(
+    command: click.Command, path: list[str]
+) -> Iterator[tuple[list[str], click.Command]]:
+    if isinstance(command, click.Group):
+        for name in sorted(command.commands):
+            yield from _iter_commands(command.commands[name], [*path, name])
+    else:
+        yield path, command
+
+
+def render_docs(root: click.Group) -> str:
+    sections = [PREAMBLE]
+    for path, command in _iter_commands(root, ["current"]):
+        arguments = [p for p in command.params if isinstance(p, click.Argument)]
+        options = [p for p in command.params if isinstance(p, click.Option) and p.name != "help"]
+
+        usage = " ".join([*path, *(f"<{a.name}>" for a in arguments)])
+        lines = [f"### {usage}"]
+        if command.help:
+            lines.append("")
+            lines.append(command.help.strip())
+        if options:
+            lines.append("")
+            lines.append("Options:")
+            for option in options:
+                parts = [f"- `{option.opts[0]}`"]
+                if option.required:
+                    parts.append("(required)")
+                if option.help:
+                    parts.append(f"- {option.help}")
+                lines.append(" ".join(parts))
+        sections.append("\n".join(lines))
+    return "\n\n".join(sections) + "\n"
+
+
+if __name__ == "__main__":
+    from .main import build_cli
+
+    print(render_docs(build_cli()), end="")

current_cli/http.py

@@ -0,0 +1,72 @@
+"""HTTP layer: authenticated requests and response rendering."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+import httpx
+from rich.console import Console
+
+from . import config
+
+# Test hook: when set, all requests go through this transport instead of the network.
+TRANSPORT: httpx.BaseTransport | None = None
+
+
+def request(
+    method: str,
+    path: str,
+    *,
+    params: dict | None = None,
+    json_body: dict | list | None = None,
+    authenticated: bool = True,
+) -> httpx.Response:
+    headers = {}
+    if authenticated:
+        token = config.get("token")
+        if token:
+            headers["Authorization"] = f"Token {token}"
+    with httpx.Client(
+        base_url=config.base_url(),
+        headers=headers,
+        timeout=30,
+        transport=TRANSPORT,
+    ) as client:
+        return client.request(method.upper(), path, params=params, json=json_body)
+
+
+def render_response(response: httpx.Response) -> None:
+    """Print the response body and exit non-zero on API errors."""
+    if response.status_code >= 400:
+        click.echo(f"Error: HTTP {response.status_code}", err=True)
+        if response.content:
+            click.echo(response.text, err=True)
+        raise SystemExit(1)
+    if not response.content:
+        return
+    try:
+        data = response.json()
+    except json.JSONDecodeError:
+        click.echo(response.text)
+        return
+    if sys.stdout.isatty():
+        Console().print_json(json.dumps(data))
+    else:
+        click.echo(json.dumps(data, indent=2))
+
+
+def parse_data_argument(value: str) -> dict | list:
+    """Parse --data as inline JSON, @file, or - for stdin."""
+    if value == "-":
+        raw = sys.stdin.read()
+    elif value.startswith("@"):
+        with open(value[1:], encoding="utf-8") as f:
+            raw = f.read()
+    else:
+        raw = value
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise click.UsageError(f"--data is not valid JSON: {exc}") from exc

current_cli/main.py

@@ -0,0 +1,159 @@
+"""CLI entry point: static auth/config commands plus schema-generated commands."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import click
+
+from . import config as config_store
+from . import http
+from .build import add_operations
+from .schema import extract_operations, load_spec
+
+MAGIC_LINK_PATH = "/api/accounts/auth/magic-link/"
+VERIFY_PATH = "/api/accounts/auth/verify/"
+LOGOUT_PATH = "/api/accounts/auth/logout/"
+ME_PATH = "/api/accounts/auth/me/"
+
+
+@click.command()
+@click.argument("email")
+def login(email: str) -> None:
+    """Sign in with a magic link and store the auth token."""
+    response = http.request(
+        "post", MAGIC_LINK_PATH, json_body={"email": email}, authenticated=False
+    )
+    if response.status_code >= 400:
+        http.render_response(response)
+        return
+
+    magic_token = response.json().get("debug_token")
+    if magic_token:
+        click.echo("Using debug token from the API (DEBUG mode).")
+    else:
+        click.echo(f"Magic link sent to {email}.")
+        magic_token = click.prompt("Paste the token from the sign-in link")
+
+    verify = http.request(
+        "post", VERIFY_PATH, json_body={"token": magic_token}, authenticated=False
+    )
+    if verify.status_code >= 400:
+        http.render_response(verify)
+        return
+
+    payload = verify.json()
+    config_store.set_value("token", payload["token"])
+    config_store.set_value("email", email)
+    click.echo(f"Logged in as {email}.")
+
+
+@click.command()
+def logout() -> None:
+    """Invalidate the auth token on the server and forget it locally."""
+    if config_store.get("token"):
+        response = http.request("post", LOGOUT_PATH)
+        if response.status_code >= 400:
+            click.echo(f"Server logout failed (HTTP {response.status_code}).", err=True)
+    config_store.unset("token")
+    config_store.unset("email")
+    click.echo("Logged out.")
+
+
+@click.command()
+def whoami() -> None:
+    """Show the current user and workspace memberships."""
+    http.render_response(http.request("get", ME_PATH))
+
+
+@click.command()
+def docs() -> None:
+    """Print a markdown reference of every command, for LLMs and humans."""
+    from .docs import render_docs
+
+    root = click.get_current_context().find_root().command
+    assert isinstance(root, click.Group)
+    click.echo(render_docs(root), nl=False)
+
+
+@click.group(name="config")
+def config_group() -> None:
+    """Read and write CLI configuration."""
+
+
+@config_group.command(name="list")
+def config_list() -> None:
+    """Show all configuration values."""
+    data = config_store.load()
+    if "token" in data:
+        data["token"] = data["token"][:6] + "..."
+    for key, value in sorted(data.items()):
+        click.echo(f"{key} = {value}")
+
+
+@config_group.command(name="get")
+@click.argument("key", type=click.Choice(config_store.KNOWN_KEYS))
+def config_get(key: str) -> None:
+    """Print one configuration value."""
+    value = config_store.get(key)
+    if value is None:
+        raise SystemExit(1)
+    click.echo(value)
+
+
+@config_group.command(name="set")
+@click.argument("key", type=click.Choice(config_store.KNOWN_KEYS))
+@click.argument("value")
+def config_set(key: str, value: str) -> None:
+    """Set one configuration value."""
+    config_store.set_value(key, value)
+    click.echo(f"{key} = {value}")
+
+
+@config_group.command(name="unset")
+@click.argument("key", type=click.Choice(config_store.KNOWN_KEYS))
+def config_unset(key: str) -> None:
+    """Remove one configuration value."""
+    config_store.unset(key)
+    click.echo(f"{key} unset")
+
+
+def build_cli(schema_source: str | None = None) -> click.Group:
+    spec = load_spec(schema_source or os.environ.get("CURRENT_SCHEMA"))
+    root = click.Group(
+        name="current",
+        help=(
+            "Command line interface for the Current API.\n\n"
+            "API commands are generated from the OpenAPI schema. Pass --schema "
+            "<path-or-url> (or set CURRENT_SCHEMA) to use a different schema, "
+            "for example <base-url>/api/schema/ for a live server."
+        ),
+    )
+    root.add_command(login)
+    root.add_command(logout)
+    root.add_command(whoami)
+    root.add_command(docs)
+    root.add_command(config_group)
+    add_operations(root, extract_operations(spec))
+    return root
+
+
+def main() -> None:
+    # --schema must be handled before click parses anything, because it
+    # determines the command tree itself.
+    argv = list(sys.argv[1:])
+    schema_source = None
+    if "--schema" in argv:
+        index = argv.index("--schema")
+        if index + 1 >= len(argv):
+            click.echo("Error: --schema requires a value.", err=True)
+            raise SystemExit(2)
+        schema_source = argv[index + 1]
+        del argv[index : index + 2]
+    cli = build_cli(schema_source)
+    cli.main(args=argv, prog_name="current")
+
+
+if __name__ == "__main__":
+    main()

current_cli/schema.py

@@ -0,0 +1,116 @@
+"""Load the OpenAPI spec and extract operations for command generation."""
+
+from __future__ import annotations
+
+import importlib.resources
+from dataclasses import dataclass
+
+import httpx
+import yaml
+
+HTTP_METHODS = ("get", "post", "put", "patch", "delete")
+
+# drf-spectacular operationIds end with the DRF action. Longest match first so
+# "partial_update" wins over "update".
+ACTION_SUFFIXES = ("partial_update", "retrieve", "destroy", "create", "update", "list")
+
+
+@dataclass(frozen=True)
+class Parameter:
+    name: str
+    location: str  # "path" or "query"
+    required: bool
+    description: str
+
+
+@dataclass(frozen=True)
+class Operation:
+    operation_id: str
+    method: str
+    path: str
+    group_path: tuple[str, ...]
+    command: str
+    description: str
+    path_params: tuple[Parameter, ...]
+    query_params: tuple[Parameter, ...]
+    has_body: bool
+
+
+def load_spec(source: str | None = None) -> dict:
+    """Load the OpenAPI spec from a path, a URL, or the bundled copy."""
+    if source is None:
+        text = importlib.resources.files("current_cli").joinpath("schema.yml").read_text("utf-8")
+    elif source.startswith(("http://", "https://")):
+        response = httpx.get(source, follow_redirects=True, timeout=30)
+        response.raise_for_status()
+        text = response.text
+    else:
+        with open(source, encoding="utf-8") as f:
+            text = f.read()
+    return yaml.safe_load(text)
+
+
+def _group_path(path: str) -> tuple[str, ...]:
+    """Derive nested command groups from URL segments.
+
+    Parameter segments are dropped and consecutive duplicates collapsed, so
+    /api/workspaces/workspaces/{workspace_id}/members/{id}/ -> (workspaces, members).
+    """
+    segments = [s for s in path.strip("/").split("/") if s and not s.startswith("{")]
+    if segments and segments[0] == "api":
+        segments = segments[1:]
+    collapsed: list[str] = []
+    for segment in segments:
+        if not collapsed or collapsed[-1] != segment:
+            collapsed.append(segment)
+    return tuple(collapsed)
+
+
+def _command_name(operation_id: str, method: str) -> str:
+    for suffix in ACTION_SUFFIXES:
+        if operation_id.endswith(suffix):
+            return suffix.replace("_", "-")
+    return method
+
+
+def extract_operations(spec: dict) -> list[Operation]:
+    operations: list[Operation] = []
+    for path, path_item in spec.get("paths", {}).items():
+        shared_params = path_item.get("parameters", [])
+        for method in HTTP_METHODS:
+            op = path_item.get(method)
+            if op is None:
+                continue
+
+            path_params: list[Parameter] = []
+            query_params: list[Parameter] = []
+            for raw in [*shared_params, *op.get("parameters", [])]:
+                param = Parameter(
+                    name=raw["name"],
+                    location=raw["in"],
+                    required=raw.get("required", False),
+                    description=raw.get("description", ""),
+                )
+                if param.location == "path":
+                    path_params.append(param)
+                elif param.location == "query":
+                    query_params.append(param)
+
+            # Positional arguments must follow their order in the URL.
+            path_params.sort(key=lambda p: path.index("{" + p.name + "}"))
+
+            operation_id = op.get("operationId", f"{method}_{path}")
+            operations.append(
+                Operation(
+                    operation_id=operation_id,
+                    method=method,
+                    path=path,
+                    group_path=_group_path(path),
+                    command=_command_name(operation_id, method),
+                    description=op.get("description", ""),
+                    path_params=tuple(path_params),
+                    query_params=tuple(query_params),
+                    has_body="requestBody" in op,
+                )
+            )
+    return operations