oaken-cli 0.1.0__py3-none-any.whl

oaken_cli/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The Oaken command-line client.
+
+The CLI is a *thin* client: it holds no business logic. Every command is a call to a registry
+operation, reached through an :class:`~oaken_cli.client.ApiClient`. In normal use that client
+speaks HTTP to the local core daemon (prompt 16); in tests it wraps the in-process
+``CoreClient`` directly, so the whole CLI is exercised without a socket.
+
+The entry point is :func:`oaken_cli.main.main`, wired as the ``oaken`` console script.
+"""
+
+from oaken_cli.main import main
+
+__all__ = ["main"]

oaken_cli/__main__.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Run the CLI as ``python -m oaken_cli``. The console script ``oaken`` is the normal entry point;
+this mirror is handy for ``python -m`` invocation and for measuring startup without the wrapper."""
+
+from __future__ import annotations
+
+from oaken_cli.main import _console_main
+
+if __name__ == "__main__":
+    _console_main()

oaken_cli/client.py

@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The seam between the CLI and core: a small, transport-neutral client.
+
+The CLI never imports core's HTTP wiring or its in-process ``CoreClient`` directly. It programs
+against :class:`ApiClient`, an abstract interface with exactly the operations a thin client needs:
+
+* :meth:`ApiClient.call` — run one registry operation (``POST /v1/ops/{name}`` over HTTP);
+* :meth:`ApiClient.list_ops` — the operation catalogue (``GET /v1/ops``), which drives both the
+  generic ``oaken op NAME`` fallback and ``--help`` text;
+* :meth:`ApiClient.stream_events` — the SSE event stream (``GET /v1/events``), for ``oaken watch``;
+* :meth:`ApiClient.health` — a liveness probe (``GET /v1/health``) used by ``oaken status``.
+
+Two implementations exist (or will):
+
+* :class:`~oaken_cli.inprocess.InProcessApiClient` wraps the in-process ``CoreClient``. It needs no
+  daemon and no socket, so the CLI's whole command surface is testable today (prompt 17).
+* ``HttpApiClient`` speaks to the running daemon. **It is a stub until prompt 16** builds the
+  server; see :mod:`oaken_cli.http`.
+
+The two results a mutation can have — it ran, or it needs confirming first — are modelled by
+:class:`CallResult`, which mirrors core's own ``CallResult`` without importing it, so the HTTP
+decoder and the in-process adapter produce the same shape.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class OpInfo:
+    """One row of the operation catalogue, as a thin client needs it.
+
+    This is the decoded form of a ``/v1/ops`` entry. It is deliberately a plain dataclass, not a
+    pydantic model: the CLI must not import the registry to describe an operation, so that a
+    registry change never forces a CLI release (the generic ``oaken op NAME`` fallback is built
+    from exactly these fields).
+    """
+
+    name: str
+    summary: str
+    permission: str  # "read" | "mutate" | "send"
+    marks_read: bool = False
+    streaming: bool = False
+    input_schema: Mapping[str, Any] = field(default_factory=dict)
+    output_schema: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Proposal:
+    """What a mutation *would* change, returned when it has not been confirmed.
+
+    The CLI shows this to the person and, for an explicit ``--yes`` or an interactive confirm,
+    calls again with ``confirmation_token``. Mirrors core's gate ``Proposal``; ``changes`` may be a
+    prefix of the whole, and ``total_changes`` is always the real count.
+    """
+
+    operation: str
+    summary: str
+    changes: list[dict[str, Any]] = field(default_factory=list)
+    total_changes: int = 0
+    confirmation_token: str = ""
+    expires_at: str = ""
+
+
+@dataclass(frozen=True)
+class CallResult:
+    """The outcome of :meth:`ApiClient.call`: either ``output`` (it ran) or ``proposal`` (confirm
+    first). ``request_id`` ties the call to an audit row and to the daemon's logs."""
+
+    request_id: str
+    output: Any | None = None
+    proposal: Proposal | None = None
+
+    @property
+    def executed(self) -> bool:
+        return self.proposal is None
+
+
+@dataclass(frozen=True)
+class Event:
+    """One line of the SSE stream: a typed event name, its JSON data, and the stream id used to
+    resume with ``Last-Event-ID`` after a reconnect."""
+
+    id: str
+    event: str
+    data: Mapping[str, Any]
+
+
+class ApiClient(ABC):
+    """The thin-client contract. An implementation decides *how* it reaches core (HTTP to the
+    daemon, or the in-process registry); the CLI only ever uses these methods.
+
+    Lifetime: an ``ApiClient`` is an async context manager so an HTTP implementation can hold a
+    connection pool and close it cleanly. The in-process implementation needs no teardown but
+    honours the same protocol.
+    """
+
+    async def __aenter__(self) -> ApiClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:  # noqa: B027 — an optional concrete hook, not abstract
+        """Release any resources (HTTP pool, etc.). The default does nothing."""
+
+    @abstractmethod
+    async def health(self) -> Mapping[str, Any]:
+        """Liveness only. Never requires a working operation; used by ``oaken status`` to tell a
+        running-but-degraded core from one that is down. Raises :class:`CoreUnavailable` when core
+        cannot be reached at all."""
+
+    @abstractmethod
+    async def list_ops(self) -> list[OpInfo]:
+        """The operations this caller may invoke, each with its schemas. Drives the generic
+        ``oaken op NAME`` fallback and the auto-derived ``--help``."""
+
+    @abstractmethod
+    async def call(
+        self,
+        name: str,
+        payload: Mapping[str, Any] | None = None,
+        *,
+        confirm: bool = False,
+        confirmation_token: str | None = None,
+        timeout: float | None = None,  # noqa: ASYNC109
+    ) -> CallResult:
+        """Run one operation. ``timeout`` (seconds) replaces the transport's default wait for the
+        answer, for the few operations that are slow by nature, such as ``ask`` on a local model.
+
+        ``confirm=True`` is the CLI saying *the person at the terminal asked for this exact
+        action*; it is how a human-class caller pre-confirms a mutation. A mutation that is neither
+        confirmed nor accompanied by a ``confirmation_token`` comes back as a :class:`Proposal` and
+        changes nothing.
+        """
+
+    @abstractmethod
+    def stream_events(self, last_event_id: str | None = None) -> AsyncIterator[Event]:
+        """Yield events as they arrive, resuming after ``last_event_id`` when given. Returns an
+        async iterator (not a coroutine) so ``oaken watch`` can ``async for`` over it."""

oaken_cli/commands/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CLI command handlers. Each module holds thin handlers that call registry operations through an
+:class:`~oaken_cli.client.ApiClient`. Imported lazily by :mod:`oaken_cli.main`."""

oaken_cli/commands/account_cmd.py

@@ -0,0 +1,349 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``oaken admin account list|show|add|set|remove`` and ``oaken auth gmail|smtp|imap``.
+
+The account wizard asks the questions and sends the answers to core, which stores them, so nobody
+edits a file by hand. Only non-secret settings are asked for or stored in the account. A credential
+is handled by ``auth``: a password is read without echo (or from stdin for scripts), sent once to
+core over loopback, and kept by the provider in the OS keyring. The CLI never prints it, never
+takes it as an argument, and never writes it to disk. Gmail's consent is core's: the CLI shows the
+address, opens a browser if asked, and waits for core to report the result.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import getpass
+import json
+import sys
+from typing import Any
+
+from oaken_cli.client import ApiClient
+from oaken_cli.commands.runtime import emit, run
+from oaken_cli.exits import CliError, ExitCode
+
+SECRETISH = ("password", "passwd", "secret", "token", "credential", "api_key", "apikey")
+PROVIDERS = ("gmail", "smtp", "imap")
+
+
+# --- admin account --------------------------------------------------------------------------
+
+
+def cmd_admin(args: argparse.Namespace) -> int:
+    if args.action == "add":
+        _require_answers_or_tty(args)
+    return run(lambda client: _admin(client, args), args)
+
+
+def _require_answers_or_tty(args: argparse.Namespace) -> None:
+    if (args.provider and args.account_id and args.name) or sys.stdin.isatty():
+        return
+    raise CliError(
+        "no terminal to ask on: give --provider, --id and --name (and --set KEY=VALUE)",
+        ExitCode.USAGE,
+    )
+
+
+async def _admin(client: ApiClient, args: argparse.Namespace) -> int:
+    if args.action == "list":
+        result = await client.call("list_accounts", {})
+        rows = result.output.get("accounts", []) if isinstance(result.output, dict) else []
+
+        def listed() -> None:
+            from oaken_cli.output import print_table, print_text
+
+            if not rows:
+                print_text('no accounts; add one with "oaken admin account add"')
+                return
+            for r in rows:
+                r["send"] = "no (receive-only)" if r.get("receive_only") else "yes"
+            print_table(rows, ["account_id", "provider", "display_name", "send"], title="accounts")
+
+        return emit(args, data=result.output, text=listed)
+    if args.action == "show":
+        result = await client.call("get_account", {"account_id": args.account_id})
+        return emit(args, data=result.output, text=lambda: _show(result.output))
+    return await _add(client, args)
+
+
+def _show(out: Any) -> None:
+    from oaken_cli.output import print_text
+
+    print_text(f"{out['account_id']}: {out['provider']} ({out['display_name']})")
+    if out.get("receive_only"):
+        print_text("  receive-only (listen but not send)")
+    caps = out.get("capabilities") or []
+    if caps:
+        print_text(f"  capabilities: {', '.join(caps)}")
+    for key, value in out.get("config", {}).items():
+        print_text(f"  {key} = {json.dumps(value)}")
+    if not out.get("config"):
+        print_text("  no settings")
+    if out.get("problem"):
+        print_text(f"problem: {out['problem']}")
+
+
+def cmd_set(args: argparse.Namespace) -> int:
+    return run(lambda client: _set(client, args), args)
+
+
+async def _set(client: ApiClient, args: argparse.Namespace) -> int:
+    # Read the current config, merge the changes, and write the whole thing back (the op replaces).
+    current = await client.call("get_account", {"account_id": args.account_id})
+    out = current.output if isinstance(current.output, dict) else {}
+    config = dict(out.get("config", {}))
+    config.update(_parse_settings(args.set))
+    receive_only = getattr(args, "receive_only", None)
+    if receive_only is True:
+        config["receive_only"] = True
+    elif receive_only is False:
+        config.pop("receive_only", None)
+    result = await client.call(
+        "set_account_config", {"account_id": args.account_id, "config": config}, confirm=True
+    )
+    body = result.output if isinstance(result.output, dict) else {}
+
+    def done() -> None:
+        from oaken_cli.output import print_text
+
+        account = body.get("account", {})
+        _show(account)
+        if body.get("restart_needed"):
+            print_text("(the running provider keeps its old settings until core restarts)")
+
+    return emit(args, data=result.output, text=done)
+
+
+def cmd_remove(args: argparse.Namespace) -> int:
+    return run(lambda client: _remove(client, args), args)
+
+
+async def _remove(client: ApiClient, args: argparse.Namespace) -> int:
+    result = await client.call("remove_account", {"account_id": args.account_id}, confirm=True)
+    out = result.output if isinstance(result.output, dict) else {}
+
+    def done() -> None:
+        from oaken_cli.output import print_text
+
+        print_text(
+            f"account {args.account_id} removed ({out.get('schedules_removed', 0)} schedules)"
+        )
+        if out.get("mail_kept"):
+            print_text("stored mail is kept; purge is a separate operation")
+        if out.get("restart_needed"):
+            print_text("(a started provider keeps serving until core restarts)")
+
+    return emit(args, data=result.output, text=done)
+
+
+async def _add(client: ApiClient, args: argparse.Namespace) -> int:
+    providers = await _providers(client)
+    interactive = sys.stdin.isatty() and not (args.provider and args.account_id and args.name)
+    provider = args.provider or _ask(f"provider ({', '.join(sorted(providers))})", "", interactive)
+    if provider not in providers:
+        raise CliError(
+            f"no provider named {provider!r}; installed: {', '.join(sorted(providers))}",
+            ExitCode.USAGE,
+        )
+    account_id = args.account_id or _ask("account id (a-z, 0-9, - and _)", provider, interactive)
+    name = args.name or _ask("display name", account_id, interactive)
+    config = _parse_settings(args.set)
+    schema = providers[provider].get("config_schema") or {}
+    if interactive:
+        config = _wizard(schema, config)
+    # Receive-only is the "listen but not send" switch (prompt 24). A new Gmail account defaults
+    # to receive-only until the user turns send on; other providers default to able-to-send.
+    receive_only = getattr(args, "receive_only", None)
+    if receive_only is None and interactive and provider == "gmail":
+        receive_only = _ask("receive only (listen but not send)? [Y/n]", "y", True).lower() in (
+            "",
+            "y",
+            "yes",
+        )
+    elif receive_only is None and provider == "gmail":
+        receive_only = True  # the honest default for a non-interactive Gmail add
+    if receive_only:
+        config["receive_only"] = True
+    result = await client.call(
+        "create_account",
+        {"account_id": account_id, "provider": provider, "display_name": name, "config": config},
+        confirm=True,
+    )
+
+    def done() -> None:
+        from oaken_cli.output import print_text
+
+        print_text(f"account {account_id} added")
+        print_text(f'next: "oaken auth {provider} --account {account_id}" to store its credential')
+
+    return emit(args, data=result.output, text=done)
+
+
+async def _providers(client: ApiClient) -> dict[str, dict[str, Any]]:
+    result = await client.call("list_plugins", {})
+    plugins = result.output.get("plugins", []) if isinstance(result.output, dict) else []
+    return {p["name"]: p for p in plugins if p.get("kind") == "provider" and "@" not in p["name"]}
+
+
+def _ask(question: str, default: str, interactive: bool) -> str:
+    if not interactive:
+        raise CliError(f"missing {question}", ExitCode.USAGE)
+    shown = f" [{default}]" if default else ""
+    answer = input(f"{question}{shown}: ").strip()
+    return answer or default
+
+
+def _parse_settings(pairs: list[str] | None) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for pair in pairs or []:
+        key, sep, value = pair.partition("=")
+        if not sep or not key:
+            raise CliError(f"--set takes KEY=VALUE, not {pair!r}", ExitCode.USAGE)
+        out[key] = _coerce(value)
+    return out
+
+
+def _coerce(text: str) -> Any:
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text
+
+
+def _wizard(schema: dict[str, Any], given: dict[str, Any]) -> dict[str, Any]:
+    """Ask for each non-secret setting the provider declares, showing its default."""
+    config = dict(given)
+    for key, spec in schema.get("properties", {}).items():
+        if key in config or any(s in key.lower() for s in SECRETISH):
+            continue
+        default = spec.get("default")
+        hint = spec.get("description") or spec.get("title") or ""
+        shown = "" if default is None else f" [{json.dumps(default)}]"
+        answer = input(f"{key}{shown}{' - ' + hint if hint else ''}: ").strip()
+        if answer:
+            config[key] = _coerce(answer)
+    return config
+
+
+# --- auth -----------------------------------------------------------------------------------
+
+
+def cmd_auth(args: argparse.Namespace) -> int:
+    password = _read_password(args) if _needs_password(args) else None
+    args.password_value = password
+    return run(lambda client: _auth(client, args), args)
+
+
+def _needs_password(args: argparse.Namespace) -> bool:
+    return args.provider in ("smtp", "imap") and not args.check
+
+
+def _read_password(args: argparse.Namespace) -> str:
+    """Without echo from a terminal, or one line from stdin; never from an argument."""
+    if args.password_stdin:
+        password = sys.stdin.readline().rstrip("\r\n")
+    elif sys.stdin.isatty():
+        password = getpass.getpass(f"{args.provider} password (not shown): ")
+    else:
+        raise CliError(
+            "no terminal to ask on; pipe the password with --password-stdin", ExitCode.USAGE
+        )
+    if not password:
+        raise CliError("no password given", ExitCode.USAGE)
+    return password
+
+
+async def _account_for(client: ApiClient, args: argparse.Namespace) -> str:
+    if args.account:
+        return str(args.account)
+    result = await client.call("list_accounts", {})
+    rows = result.output.get("accounts", []) if isinstance(result.output, dict) else []
+    mine = [a["account_id"] for a in rows if a.get("provider") == args.provider]
+    if len(mine) == 1:
+        return str(mine[0])
+    if not mine:
+        raise CliError(
+            f'no {args.provider} account; add one with "oaken admin account add"', ExitCode.USAGE
+        )
+    raise CliError(
+        f"several {args.provider} accounts ({', '.join(mine)}); use --account", ExitCode.USAGE
+    )
+
+
+async def _auth(client: ApiClient, args: argparse.Namespace) -> int:
+    account = await _account_for(client, args)
+    if args.check:
+        return await _check(client, args, account)
+    if args.provider == "gmail":
+        return await _consent(client, args, account)
+    await client.call(
+        "set_account_password",
+        {"account_id": account, "password": args.password_value},
+        confirm=True,
+    )
+    args.password_value = None
+    return await _check(client, args, account, stored=True)
+
+
+async def _check(
+    client: ApiClient, args: argparse.Namespace, account: str, *, stored: bool = False
+) -> int:
+    result = await client.call("check_account", {"account_id": account})
+    out = result.output if isinstance(result.output, dict) else {}
+
+    def text() -> None:
+        from oaken_cli.output import print_text
+
+        if stored:
+            print_text(f"password for {account} stored in the OS keyring")
+        print_text(
+            f"{account}: login works"
+            if out.get("ok")
+            else f"{account}: {out.get('detail', 'failed')}"
+        )
+
+    emit(args, data={"account_id": account, "stored": stored, **out}, text=text)
+    return int(ExitCode.OK if out.get("ok") else ExitCode.AUTH)
+
+
+async def _consent(client: ApiClient, args: argparse.Namespace, account: str) -> int:
+    started = await client.call("start_authorization", {"account_id": account}, confirm=True)
+    url = str((started.output or {}).get("url", "")) if isinstance(started.output, dict) else ""
+    if not args.json:
+        from oaken_cli.output import print_text
+
+        print_text(f"open this address to authorize {account}:\n{url}")
+        if not args.no_browser and sys.stdout.isatty():
+            import webbrowser
+
+            webbrowser.open(url)
+        print_text("waiting for Google to redirect back to this machine...")
+    state, detail = await _wait_authorized(client, account, args.timeout)
+
+    def text() -> None:
+        from oaken_cli.output import print_text
+
+        if state == "done":
+            print_text(f"{account} authorized; the refresh token is in the OS keyring")
+        else:
+            print_text(f"{account}: {detail or 'authorization did not finish'}")
+
+    emit(
+        args, data={"account_id": account, "state": state, "detail": detail, "url": url}, text=text
+    )
+    return int(ExitCode.OK if state == "done" else ExitCode.AUTH)
+
+
+async def _wait_authorized(client: ApiClient, account: str, timeout: float) -> tuple[str, str]:  # noqa: ASYNC109
+    async def poll() -> tuple[str, str]:
+        while True:
+            result = await client.call("authorization_status", {"account_id": account})
+            out = result.output if isinstance(result.output, dict) else {}
+            if out.get("state") in ("done", "failed"):
+                return str(out["state"]), str(out.get("detail", ""))
+            await asyncio.sleep(0.5)
+
+    try:
+        return await asyncio.wait_for(poll(), timeout)
+    except TimeoutError:
+        return "failed", f"timed out after {timeout:.0f}s; nothing was changed"