hoja-cli 0.21.4__py3-none-any.whl

google_workspace/tools.py

@@ -0,0 +1,64 @@
+"""Read-only connector operations. Each takes a verified Principal and resolves accounts from the database."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import datetime
+
+import httpx
+
+from google_workspace.client import (
+    CalendarEvent,
+    Document,
+    DriveFile,
+    GmailMessage,
+    GoogleWorkspaceClient,
+)
+from google_workspace.errors import ConnectorAuthError
+from google_workspace.principal import Principal
+
+
+@dataclass(frozen=True)
+class AccountGrant:
+    """A connected account the principal may use. `access_token` returns a fresh token."""
+
+    account_id: str
+    external_account: str
+    access_token: Callable[[], Awaitable[str]]
+
+
+async def _client_for(http: httpx.AsyncClient, grant: AccountGrant) -> GoogleWorkspaceClient:
+    token = await grant.access_token()
+    if not token:
+        raise ConnectorAuthError(
+            "Google account has no usable access token.", hint="Reconnect the account."
+        )
+    return GoogleWorkspaceClient(http, token)
+
+
+async def gmail_search(
+    http: httpx.AsyncClient, grant: AccountGrant, query: str, max_results: int = 10
+) -> list[GmailMessage]:
+    return await (await _client_for(http, grant)).gmail_search(query, max_results)
+
+
+async def drive_search(
+    http: httpx.AsyncClient, grant: AccountGrant, query: str, max_results: int = 10
+) -> list[DriveFile]:
+    return await (await _client_for(http, grant)).drive_search(query, max_results)
+
+
+async def calendar_events(
+    http: httpx.AsyncClient, grant: AccountGrant, start: datetime, end: datetime
+) -> list[CalendarEvent]:
+    return await (await _client_for(http, grant)).calendar_events(start, end)
+
+
+async def docs_get(http: httpx.AsyncClient, grant: AccountGrant, document_id: str) -> Document:
+    return await (await _client_for(http, grant)).docs_get(document_id)
+
+
+def require_read(principal: Principal) -> None:
+    if principal.scope not in {"read", "write"}:
+        raise ConnectorAuthError("Principal lacks read scope.")

google_workspace/writes.py

@@ -0,0 +1,44 @@
+"""Write operations available through the approval queue. Only the names in WRITE_TOOLS can run,
+and each one validates its arguments before any request reaches Google."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+import httpx
+
+from google_workspace.client import GoogleWorkspaceClient
+from google_workspace.tools import AccountGrant
+
+WRITE_TOOLS = ("gmail_send", "calendar_event_create", "docs_append_text")
+
+
+def _str(args: dict[str, Any], key: str, limit: int) -> str:
+    value = args.get(key)
+    if not isinstance(value, str) or not value.strip() or len(value) > limit:
+        raise ValueError(f"{key} must be a non-empty string up to {limit} characters.")
+    return value
+
+
+async def run_write(
+    http: httpx.AsyncClient, grant: AccountGrant, tool: str, args: dict[str, Any]
+) -> str:
+    """Execute one approved write. Returns a short, non-sensitive summary for the audit row."""
+    if tool not in WRITE_TOOLS:
+        raise ValueError(f"Unknown write tool: {tool}")
+    client = GoogleWorkspaceClient(http, await grant.access_token())
+    if tool == "gmail_send":
+        message_id = await client.gmail_send(
+            to=_str(args, "to", 320),
+            subject=_str(args, "subject", 200),
+            body=_str(args, "body", 20000),
+        )
+        return f"sent message {message_id}"
+    if tool == "calendar_event_create":
+        start = datetime.fromisoformat(_str(args, "start", 64))
+        end = datetime.fromisoformat(_str(args, "end", 64))
+        event_id = await client.calendar_event_create(_str(args, "summary", 200), start, end)
+        return f"created event {event_id}"
+    await client.docs_append_text(_str(args, "document_id", 200), _str(args, "text", 20000))
+    return "appended text"

hoja/__init__.py

@@ -0,0 +1,29 @@
+"""Hoja — self-hosted, agent-native work management."""
+
+from pathlib import Path
+
+#: PyPI distribution that ships this package. The project cannot be named
+#: ``hoja`` on PyPI (that name belongs to unrelated software), so it is
+#: published as ``hoja-cli``. Anything that talks to PyPI — the ``hoja update``
+#: command, install instructions, release tooling — must use this name. The
+#: commands stay ``hoja``, ``hoja-mcp``, and ``hoja-serve``.
+DISTRIBUTION_NAME = "hoja-cli"
+
+
+def _read_version() -> str:
+    """Read version from VERSION file at the repo root.
+
+    Falls back to a hardcoded string if the file is missing (e.g. when
+    installed from a wheel where VERSION isn't packaged).
+    """
+    try:
+        version_file = Path(__file__).resolve().parent.parent / "VERSION"
+        if version_file.is_file():
+            return version_file.read_text(encoding="utf-8").strip()
+    except OSError:
+        pass
+    return "0.7.0"
+
+
+__version__ = _read_version()
+__all__ = ["DISTRIBUTION_NAME", "__version__"]

hoja/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m hoja`."""
+
+from hoja.cli import app
+
+if __name__ == "__main__":
+    app()

hoja/auth.py

@@ -0,0 +1,42 @@
+"""Authentication helpers.
+
+Token resolution lives in `config.py`. This module wraps viewer caching
+so we can resolve "me" without an extra API call when the user passes
+`--assignee me`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from hoja.client import LinearClient
+from hoja.graphql import queries
+from hoja.models.user import User
+
+_viewer_cache: User | None = None
+_viewer_lock = asyncio.Lock()
+
+
+async def get_viewer(client: LinearClient, *, refresh: bool = False) -> User:
+    """Return the currently-authenticated user.
+
+    Cached per-process so repeated --assignee me resolutions don't
+    cost an API call each.
+    """
+    global _viewer_cache
+    if _viewer_cache is not None and not refresh:
+        return _viewer_cache
+
+    async with _viewer_lock:
+        if _viewer_cache is not None and not refresh:
+            return _viewer_cache
+        _viewer_cache = await client.execute_as(
+            User, queries.VIEWER, path=["viewer"], operation="Viewer"
+        )
+        return _viewer_cache
+
+
+def reset_viewer_cache() -> None:
+    """Reset cached viewer (used after logout/token change)."""
+    global _viewer_cache
+    _viewer_cache = None

hoja/cli.py

@@ -0,0 +1,161 @@
+"""Root CLI entrypoint.
+
+Defines the top-level Typer app, global flags, error handling, and
+registers all subcommand modules.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+import typer
+
+from hoja import DISTRIBUTION_NAME, __version__
+from hoja.cli_state import CLIState, set_state
+from hoja.commands.auth_cmd import auth_app, me_app
+from hoja.commands.comment import comment_app
+from hoja.commands.cycle import cycle_app
+from hoja.commands.init import init_app
+from hoja.commands.issue import issue_app
+from hoja.commands.label import label_app
+from hoja.commands.memory import memory_app
+from hoja.commands.project import project_app
+from hoja.commands.raw import raw_app
+from hoja.commands.team import team_app
+from hoja.commands.update import update_app
+from hoja.config import load_config, resolve_account, resolve_base_url, resolve_token
+from hoja.errors import HojaError
+from hoja.models.enums import OutputFormat
+from hoja.output import emit_error
+
+app = typer.Typer(
+    name="hoja",
+    help=(
+        "Hoja CLI — agent-native work management for Hoja and Linear-compatible "
+        f"services (installed from the PyPI package {DISTRIBUTION_NAME})"
+    ),
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+)
+
+
+def _version_cb(value: bool) -> None:
+    if value:
+        typer.echo(f"hoja {__version__} (PyPI: {DISTRIBUTION_NAME})")
+        raise typer.Exit()
+
+
+def _team_key_hint_from_argv(argv: list[str]) -> str | None:
+    """Best-effort scan of argv for a team key, used for account selection.
+
+    The root callback runs before subcommands parse their own options, so we
+    sniff argv for either a ``--team/-t <value>`` option or a bare issue
+    identifier like ``SWA-20``. This is purely a hint — it only influences
+    which account (token) is chosen, never what the subcommand does.
+    """
+    for i, arg in enumerate(argv):
+        if arg in ("--team", "-t") and i + 1 < len(argv):
+            return argv[i + 1]
+        if arg.startswith("--team="):
+            return arg.split("=", 1)[1]
+    # Fall back to the first issue-identifier-looking positional (KEY-123).
+    for arg in argv:
+        if arg.startswith("-"):
+            continue
+        head, sep, tail = arg.partition("-")
+        if sep and head.isalpha() and tail.isdigit():
+            return arg
+    return None
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    token: Optional[str] = typer.Option(None, "--token", envvar=None, help="Hoja API token (overrides $HOJA_TOKEN)"),
+    account: Optional[str] = typer.Option(None, "--account", "-a", envvar=None, help="Account name to use (overrides workspace/default)"),
+    output: OutputFormat = typer.Option(OutputFormat.HUMAN, "--output", "-o", help="Output format"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Print GraphQL operations to stderr"),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Suppress non-essential output"),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable ANSI colors"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Print mutations without executing"),
+    timeout: float = typer.Option(30.0, "--timeout", help="HTTP timeout in seconds"),
+    version: Optional[bool] = typer.Option(
+        None, "--version", callback=_version_cb, is_eager=True, help="Show version and exit"
+    ),
+) -> None:
+    """Global flags applied before any subcommand."""
+    # Resolve config + account + token
+    config = load_config()
+
+    # Account resolution: only required for commands that hit the API.
+    # We defer the actual AuthError to first API call to allow `--help` etc.
+    try:
+        team_hint = _team_key_hint_from_argv(sys.argv[1:])
+        account_name, account_cfg = resolve_account(
+            account, config, team_key=team_hint
+        )
+        resolved_token = resolve_token(token, account_cfg)
+        resolved_base_url = resolve_base_url(None, account_cfg)
+    except HojaError:
+        account_name = ""
+        resolved_token = ""
+        resolved_base_url = None
+
+    state = CLIState(
+        token=resolved_token,
+        config=config,
+        output=output,
+        verbose=verbose,
+        quiet=quiet,
+        no_color=no_color,
+        dry_run=dry_run,
+        timeout=timeout,
+        account_name=account_name,
+        base_url=resolved_base_url,
+    )
+    set_state(state)
+
+
+# Register subcommands
+app.add_typer(me_app, name="me")
+app.add_typer(auth_app, name="auth")
+app.add_typer(init_app, name="init")
+app.add_typer(team_app, name="team")
+app.add_typer(issue_app, name="issue")
+app.add_typer(project_app, name="project")
+app.add_typer(cycle_app, name="cycle")
+app.add_typer(comment_app, name="comment")
+app.add_typer(label_app, name="label")
+app.add_typer(memory_app, name="memory")
+app.add_typer(raw_app, name="raw")
+app.add_typer(update_app, name="update")
+
+
+def _entry() -> None:
+    """Wrap typer_app() with consistent error handling and exit codes."""
+    try:
+        typer_app()
+    except HojaError as e:
+        from hoja.cli_state import get_state
+        state = get_state()
+        if state.output == OutputFormat.JSON:
+            import json as _json
+            print(_json.dumps(e.to_dict(), indent=2), file=sys.stderr)
+        else:
+            emit_error(e.message, hint=e.hint)
+        sys.exit(int(e.exit_code))
+    except KeyboardInterrupt:
+        emit_error("Interrupted")
+        sys.exit(130)
+
+
+# Public callable for `hoja` script entry point in pyproject.toml.
+# Renamed to `typer_app` internally so the wrapper is what pip-installed
+# `hoja` actually invokes.
+typer_app = app
+app = _entry  # type: ignore[assignment]
+
+
+if __name__ == "__main__":
+    _entry()

hoja/cli_state.py

@@ -0,0 +1,55 @@
+"""Shared CLI state — populated by the root callback, read by subcommands.
+
+Typer doesn't have a great way to share state across commands without going
+through Context. We use a small module-level container to keep subcommands
+clean.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from hoja.client import LinearClient
+from hoja.config import Config
+from hoja.models.enums import OutputFormat
+
+
+@dataclass
+class CLIState:
+    """Mutable per-invocation state."""
+
+    token: str = ""
+    config: Config = field(default_factory=Config)
+    output: OutputFormat = OutputFormat.HUMAN
+    verbose: bool = False
+    quiet: bool = False
+    no_color: bool = False
+    dry_run: bool = False
+    timeout: float = 30.0
+    account_name: str = ""  # active account name for context display
+    base_url: str | None = None  # GraphQL endpoint override (local backend)
+
+
+_state = CLIState()
+
+
+def get_state() -> CLIState:
+    return _state
+
+
+def set_state(state: CLIState) -> None:
+    global _state
+    _state = state
+
+
+def build_client(state: CLIState | None = None) -> LinearClient:
+    """Construct a LinearClient configured from the current CLI state."""
+    s = state or _state
+    kwargs = dict(
+        token=s.token,
+        timeout=s.timeout,
+        verbose=s.verbose,
+    )
+    if s.base_url:
+        kwargs["base_url"] = s.base_url
+    return LinearClient(**kwargs)

hoja/client.py

@@ -0,0 +1,268 @@
+"""Async GraphQL client for Hoja's Linear-compatible GraphQL API.
+
+Design goals:
+- Single httpx.AsyncClient with sensible defaults (HTTP/2, timeout, retries).
+- Token never logged in plaintext (redacted in verbose mode).
+- GraphQL errors lifted into typed exceptions.
+- Rate limit awareness (X-RateLimit-* headers honored).
+- Cursor-based pagination helper.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, AsyncIterator, TypeVar
+
+import httpx
+from pydantic import BaseModel
+
+from hoja import __version__
+from hoja.config import redact_token
+from hoja.errors import (
+    APIError,
+    AuthError,
+    NetworkError,
+    RateLimitError,
+    ValidationError,
+)
+
+logger = logging.getLogger("hoja.client")
+
+# Endpoint used when no --api-url flag, $HOJA_API_URL (or deprecated
+# $LINEAR_API_URL), or accounts.<name>.base_url is configured. Point the client
+# at your own `hoja-serve` instance (e.g. http://127.0.0.1:8787/graphql) to stay
+# fully self-hosted; this fallback is the public Linear-compatible API.
+DEFAULT_API_URL = "https://api.linear.app/graphql"
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class LinearClient:
+    """Async GraphQL client for a Linear-compatible GraphQL API."""
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str = DEFAULT_API_URL,
+        timeout: float = 30.0,
+        verbose: bool = False,
+    ) -> None:
+        self._token = token
+        self._base_url = base_url
+        self._verbose = verbose
+        self._http = httpx.AsyncClient(
+            http2=False,  # httpx[http2] is a separate dep — keep deps minimal
+            timeout=timeout,
+            headers={
+                "Authorization": token,
+                "Content-Type": "application/json",
+                "User-Agent": f"hoja/{__version__} (+https://github.com/rinadelph/hoja)",
+            },
+        )
+
+    async def __aenter__(self) -> "LinearClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    # ------------------------------------------------------------------
+    # Core request method
+    # ------------------------------------------------------------------
+
+    async def execute(
+        self,
+        query: str,
+        variables: dict[str, Any] | None = None,
+        *,
+        operation: str | None = None,
+    ) -> dict[str, Any]:
+        """Execute a GraphQL query/mutation. Returns the `data` portion.
+
+        Raises:
+            AuthError: 401
+            RateLimitError: 429
+            APIError: GraphQL errors in response
+            NetworkError: transport-level failures
+        """
+        payload: dict[str, Any] = {"query": query}
+        if variables:
+            # Drop None values — Linear's API rejects explicit nulls in many inputs
+            payload["variables"] = _strip_none(variables)
+        if operation:
+            payload["operationName"] = operation
+
+        if self._verbose:
+            logger.info(
+                "POST %s [token=%s] op=%s vars=%s",
+                self._base_url,
+                redact_token(self._token),
+                operation or "<anon>",
+                json.dumps(payload.get("variables", {}), default=str)[:200],
+            )
+
+        try:
+            resp = await self._http.post(self._base_url, json=payload)
+        except httpx.TimeoutException as e:
+            raise NetworkError(f"Request timed out: {e}") from e
+        except httpx.RequestError as e:
+            raise NetworkError(f"Network error: {e}") from e
+
+        # Handle HTTP-level errors
+        if resp.status_code == 401:
+            raise AuthError(
+                "The API rejected the token (HTTP 401)",
+                hint="Mint a new token in your workspace, or check $HOJA_TOKEN",
+            )
+        if resp.status_code == 429:
+            retry = resp.headers.get("Retry-After")
+            raise RateLimitError(
+                "API rate limit exceeded",
+                retry_after=int(retry) if retry and retry.isdigit() else None,
+            )
+        if resp.status_code >= 500:
+            raise APIError(
+                f"The API returned HTTP {resp.status_code}",
+                hint="This is usually transient — retry in a few seconds",
+            )
+        if resp.status_code >= 400:
+            raise APIError(
+                f"HTTP {resp.status_code}: {resp.text[:500]}",
+            )
+
+        try:
+            body = resp.json()
+        except json.JSONDecodeError as e:
+            raise APIError(f"Non-JSON response from Linear: {e}") from e
+
+        # GraphQL-level errors
+        if errors := body.get("errors"):
+            messages = "; ".join(e.get("message", "<unknown>") for e in errors)
+            raise APIError(messages, errors=errors)
+
+        data = body.get("data")
+        if data is None:
+            raise APIError("Linear returned empty data")
+        return data
+
+    # ------------------------------------------------------------------
+    # Typed helpers
+    # ------------------------------------------------------------------
+
+    async def execute_as(
+        self,
+        model: type[T],
+        query: str,
+        variables: dict[str, Any] | None = None,
+        *,
+        path: list[str] | None = None,
+        operation: str | None = None,
+    ) -> T:
+        """Execute and validate the response against a Pydantic model.
+
+        path: list of dict keys to drill down to before parsing.
+            e.g. ["viewer"] turns {"viewer": {...}} into the viewer object.
+        """
+        data = await self.execute(query, variables, operation=operation)
+        node: Any = data
+        for key in path or []:
+            if not isinstance(node, dict) or key not in node:
+                raise ValidationError(
+                    f"Expected key {key!r} in response path "
+                    f"{'.'.join(path or [])}",
+                )
+            node = node[key]
+        try:
+            return model.model_validate(node)
+        except Exception as e:
+            raise ValidationError(
+                f"Response did not match {model.__name__}: {e}",
+            ) from e
+
+    async def execute_list(
+        self,
+        model: type[T],
+        query: str,
+        variables: dict[str, Any] | None = None,
+        *,
+        path: list[str],
+        operation: str | None = None,
+    ) -> list[T]:
+        """Execute and validate a connection.nodes list response.
+
+        path should end at the dict containing 'nodes'.
+        """
+        data = await self.execute(query, variables, operation=operation)
+        node: Any = data
+        for key in path:
+            if not isinstance(node, dict) or key not in node:
+                raise ValidationError(
+                    f"Expected key {key!r} at path {'.'.join(path)}",
+                )
+            node = node[key]
+        if not isinstance(node, dict) or "nodes" not in node:
+            raise ValidationError(
+                "Expected a connection object with 'nodes' at path "
+                f"{'.'.join(path)}"
+            )
+        try:
+            return [model.model_validate(item) for item in node["nodes"]]
+        except Exception as e:
+            raise ValidationError(
+                f"List items did not match {model.__name__}: {e}",
+            ) from e
+
+    # ------------------------------------------------------------------
+    # Pagination
+    # ------------------------------------------------------------------
+
+    async def paginate(
+        self,
+        query: str,
+        variables: dict[str, Any],
+        *,
+        path: list[str],
+        page_size: int = 50,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Yield every node across all pages of a connection."""
+        cursor: str | None = None
+        while True:
+            vars_with_cursor = {**variables, "first": page_size}
+            if cursor:
+                vars_with_cursor["after"] = cursor
+            data = await self.execute(query, vars_with_cursor)
+            node: Any = data
+            for key in path:
+                node = node[key]
+            for item in node.get("nodes", []):
+                yield item
+            page_info = node.get("pageInfo") or {}
+            if not page_info.get("hasNextPage"):
+                break
+            cursor = page_info.get("endCursor")
+            if not cursor:
+                break
+
+
+def _strip_none(d: dict[str, Any]) -> dict[str, Any]:
+    """Recursively remove None values from a dict for GraphQL variables."""
+    if not isinstance(d, dict):
+        return d
+    out: dict[str, Any] = {}
+    for k, v in d.items():
+        if v is None:
+            continue
+        if isinstance(v, dict):
+            stripped = _strip_none(v)
+            if stripped:
+                out[k] = stripped
+        elif isinstance(v, list):
+            out[k] = [_strip_none(item) if isinstance(item, dict) else item for item in v]
+        else:
+            out[k] = v
+    return out

hoja/commands/__init__.py

@@ -0,0 +1,4 @@
+"""Command modules.
+
+Each file exports a Typer sub-app registered in hoja.cli.
+"""