glossa-cli 0.1.0__3-py3-none-any.whl

glossa_cli/cli.py

@@ -0,0 +1,477 @@
+"""Glossa command-line interface.
+
+Subcommands:
+    glossa login     — sign in (browser OAuth)
+    glossa logout    — sign out
+    glossa analyze   — CEFR-leveled word/phrase breakdown of arbitrary text
+    glossa add       — add a word/phrase to your vocabulary
+    glossa set       — change a word's state (saved / learning / known)
+    glossa list      — list your vocabulary
+    glossa review    — interactive FSRS review session
+    glossa lang      — show or set your default learning language
+"""
+
+import asyncio
+import json
+import os
+import sys
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import httpx
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from glossa_cli import config
+from glossa_cli.auth import clear_credentials
+from glossa_cli.client import GlossaApiError, GlossaClient
+
+app = typer.Typer(
+    help="Glossa vocabulary CLI — analyze text and manage your vocabulary.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+console = Console()
+err_console = Console(stderr=True)
+
+LANGUAGES = {"en", "fr", "pt-PT"}
+STATUSES = {"saved", "learning", "known"}
+RATINGS = {1: "Again", 2: "Hard", 3: "Good", 4: "Easy"}
+
+
+# ── Shared helpers ─────────────────────────────────────────────────────────────
+
+
+def _format_error(exc: Exception) -> str:
+    if isinstance(exc, GlossaApiError):
+        if exc.status_code == 401:
+            return (
+                "Glossa rejected your credentials. Generate a token in "
+                "Glossa → Settings → Tokens and export it as GLOSSA_API_TOKEN, "
+                "or omit it to use the browser sign-in flow."
+            )
+        if (
+            isinstance(exc.detail, dict)
+            and exc.detail.get("error") == "multiple_languages"
+        ):
+            enabled = exc.detail.get("enabled") or []
+            joined = ", ".join(enabled) if enabled else "(none)"
+            return (
+                "You have multiple learning languages enabled: "
+                f"{joined}.\nPick one for this command, or set a default:\n"
+                "  --lang <code>                # one-off override\n"
+                "  export GLOSSA_LANG=<code>    # session\n"
+                "  glossa lang set <code>       # persistent"
+            )
+        if exc.status_code == 404:
+            return f"Not found: {exc.detail}"
+        return f"Glossa API error ({exc.status_code}): {exc.detail}"
+    if isinstance(exc, httpx.HTTPError):
+        return (
+            f"Could not reach Glossa at {os.environ.get('GLOSSA_API_URL', '')!r}: {exc}. "
+            "Is the backend running and GLOSSA_API_URL correct?"
+        )
+    return f"Glossa error: {exc}"
+
+
+def _run(fn: Callable[[GlossaClient], Awaitable[Any]]) -> Any:
+    """Open an authenticated client, run *fn*, and surface errors as exit code 1."""
+
+    async def _wrap() -> Any:
+        async with GlossaClient() as client:
+            return await fn(client)
+
+    try:
+        return asyncio.run(_wrap())
+    except (GlossaApiError, RuntimeError, httpx.HTTPError) as exc:
+        err_console.print(f"[red]{_format_error(exc)}[/red]")
+        raise typer.Exit(1) from exc
+
+
+def _validate_lang(language_code: str | None) -> None:
+    if language_code is not None and language_code not in LANGUAGES:
+        err_console.print(
+            f"[red]Unknown language '{language_code}'. Choose from: "
+            f"{', '.join(sorted(LANGUAGES))}.[/red]"
+        )
+        raise typer.Exit(2)
+
+
+def _validate_status(status: str) -> None:
+    if status not in STATUSES:
+        err_console.print(
+            f"[red]Invalid status '{status}'. Choose from: "
+            f"{', '.join(sorted(STATUSES))}.[/red]"
+        )
+        raise typer.Exit(2)
+
+
+# ── Commands ───────────────────────────────────────────────────────────────────
+
+
+@app.command()
+def login(
+    force: bool = typer.Option(
+        False, "--force", help="Clear cached credentials and sign in again."
+    ),
+) -> None:
+    """Sign in to Glossa. Run this first — opens a browser to authorise you."""
+    using_token = bool(os.environ.get("GLOSSA_API_TOKEN"))
+
+    if force and not using_token and clear_credentials():
+        console.print("[dim]Cleared saved credentials.[/dim]")
+
+    # Opening the client runs the OAuth device flow (printing an auth URL) when
+    # there's no usable token; the tiny authenticated call then confirms it worked.
+    _run(lambda c: c.reviews_due(limit=1))
+
+    if using_token:
+        console.print("[green]✓ Signed in with your GLOSSA_API_TOKEN.[/green]")
+    else:
+        console.print(
+            "[green]✓ Signed in.[/green] You're ready to use Glossa — try "
+            "[bold]glossa list[/bold]."
+        )
+
+
+@app.command()
+def logout() -> None:
+    """Sign out — remove cached OAuth credentials.
+
+    Idempotent: if nothing's cached, says so and exits 0. If a
+    ``GLOSSA_API_TOKEN`` is set in your environment, the CLI still uses it
+    until you unset it — `logout` warns you about that.
+    """
+    if os.environ.get("GLOSSA_API_TOKEN"):
+        err_console.print(
+            "[yellow]Note: GLOSSA_API_TOKEN is set in your environment — the "
+            "CLI will keep using it until you unset it.[/yellow]"
+        )
+    if clear_credentials():
+        console.print(
+            "[green]✓ Signed out.[/green] Cached credentials removed from "
+            "~/.config/glossa/credentials.json."
+        )
+    else:
+        console.print("[dim]Already signed out — no cached credentials.[/dim]")
+
+
+@app.command()
+def analyze(
+    text: str | None = typer.Argument(
+        None, help="Text to analyze. Omit to read --file or stdin."
+    ),
+    file: str | None = typer.Option(None, "--file", "-f", help="Read text from this file."),
+    as_json: bool = typer.Option(False, "--json", help="Print the raw JSON response."),
+) -> None:
+    """Analyze text and show its vocabulary breakdown (CEFR levels, phrases).
+
+    Language is auto-detected from the text.
+    """
+    if file is not None:
+        try:
+            with open(file, encoding="utf-8") as fh:
+                content = fh.read()
+        except OSError as exc:
+            err_console.print(f"[red]Cannot read {file}: {exc}[/red]")
+            raise typer.Exit(2) from exc
+    elif text is not None:
+        content = text
+    elif not sys.stdin.isatty():
+        content = sys.stdin.read()
+    else:
+        err_console.print("[red]No text provided. Pass TEXT, --file, or pipe via stdin.[/red]")
+        raise typer.Exit(2)
+
+    if not content.strip():
+        err_console.print("[red]Empty input.[/red]")
+        raise typer.Exit(2)
+
+    result = _run(lambda c: c.analyze_text(content))
+
+    if as_json:
+        console.print_json(json.dumps(result))
+        return
+
+    words = result.get("words", [])
+    table = Table(title="Vocabulary breakdown")
+    table.add_column("Lemma", style="bold")
+    table.add_column("POS")
+    table.add_column("Count", justify="right")
+    table.add_column("CEFR")
+    table.add_column("Type")
+    for w in words:
+        kind = w.get("type", "word")
+        if kind == "phrase" and w.get("pattern_type"):
+            kind = f"phrase · {w['pattern_type']}"
+        table.add_row(
+            w.get("lemma", ""),
+            w.get("part_of_speech", "") or "",
+            str(w.get("occurrences", "")),
+            w.get("cefr_level") or "—",
+            kind,
+        )
+    console.print(table)
+    console.print(
+        f"[dim]{result.get('unique_lemmas', 0)} unique lemmas · "
+        f"{result.get('unique_phrases', 0)} phrases · "
+        f"{result.get('total_tokens', 0)} tokens[/dim]"
+    )
+
+
+@app.command()
+def add(
+    lemma: str = typer.Argument(..., help="Dictionary form, e.g. 'serendipity' or 'break the ice'."),  # noqa: E501
+    pos: str | None = typer.Option(None, "--pos", help="NOUN, VERB, ADJ, or ADV."),
+    status: str = typer.Option("learning", "--status", "-s", help="saved, learning, or known."),
+    translation: str | None = typer.Option(None, "--translation", "-t", help="Your translation."),
+    lang: str | None = typer.Option(
+        None, "--lang", "-l", hidden=True,
+        help="Override the language (en/fr/pt-PT). Usually inferred from your account.",
+    ),
+) -> None:
+    """Add a word or phrase to your vocabulary."""
+    _validate_status(status)
+    language_code = config.resolve_language(lang)
+    _validate_lang(language_code)
+    result = _run(
+        lambda c: c.add_word(
+            lemma=lemma,
+            language_code=language_code,
+            part_of_speech=pos,
+            status=status,
+            translation=translation,
+        )
+    )
+    _print_vocab_item(result, action="Saved")
+
+
+@app.command(name="set")
+def set_status(
+    lemma: str = typer.Argument(..., help="The word/phrase to update (or pass --id instead)."),
+    status: str = typer.Argument(..., help="New state: saved, learning, or known."),
+    pos: str | None = typer.Option(None, "--pos", help="NOUN, VERB, ADJ, or ADV."),
+    translation: str | None = typer.Option(None, "--translation", "-t", help="Your translation."),
+    entry_id: int | None = typer.Option(
+        None, "--id", help="Update a specific lexical_entry_id (from `glossa list`) precisely."
+    ),
+    lang: str | None = typer.Option(
+        None, "--lang", "-l", hidden=True,
+        help="Override the language (en/fr/pt-PT). Usually inferred from your account.",
+    ),
+) -> None:
+    """Change a word's state. By default upserts by lemma; --id targets one sense."""
+    _validate_status(status)
+    if entry_id is not None:
+        result = _run(
+            lambda c: c.update_status(
+                lexical_entry_id=entry_id, status=status, user_translation=translation
+            )
+        )
+    else:
+        language_code = config.resolve_language(lang)
+        _validate_lang(language_code)
+        result = _run(
+            lambda c: c.add_word(
+                lemma=lemma,
+                language_code=language_code,
+                part_of_speech=pos,
+                status=status,
+                translation=translation,
+            )
+        )
+    _print_vocab_item(result, action="Updated")
+
+
+@app.command(name="list")
+def list_words(
+    status: str | None = typer.Option(
+        None, "--status", "-s", help="Filter: saved, learning, or known."
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Print the raw JSON response."),
+) -> None:
+    """List your vocabulary across all enabled languages."""
+    if status is not None:
+        _validate_status(status)
+    items = _run(lambda c: c.list_vocabulary(status=status))
+
+    if as_json:
+        console.print_json(json.dumps(items))
+        return
+
+    if not items:
+        console.print("[dim]No matching words.[/dim]")
+        return
+
+    table = Table(title="Your vocabulary")
+    table.add_column("ID", justify="right", style="dim")
+    table.add_column("Lemma", style="bold")
+    table.add_column("POS")
+    table.add_column("Lang")
+    table.add_column("Status")
+    table.add_column("CEFR")
+    table.add_column("Next review")
+    for it in items:
+        table.add_row(
+            str(it.get("lexical_entry_id", "")),
+            it.get("lemma") or "",
+            it.get("part_of_speech") or "",
+            it.get("language_code") or "",
+            it.get("status") or "",
+            it.get("cefr_level") or "—",
+            _fmt_dt(it.get("next_review")),
+        )
+    console.print(table)
+    console.print(f"[dim]{len(items)} word(s)[/dim]")
+
+
+@app.command()
+def review(
+    limit: int = typer.Option(50, "--limit", help="Max cards to fetch (1–200)."),
+) -> None:
+    """Interactive FSRS review of words that are due."""
+    cards = _run(lambda c: c.reviews_due(limit=limit))
+
+    if not cards:
+        console.print("[green]Nothing due for review — you're all caught up![/green]")
+        return
+
+    console.print(
+        f"[bold]{len(cards)}[/bold] card(s) due. Rate each: "
+        r"1 Again  2 Hard  3 Good  4 Easy  (q to quit)" + "\n"
+    )
+
+    reviewed = 0
+    for idx, card in enumerate(cards, start=1):
+        console.print(
+            f"[dim]{idx}/{len(cards)}[/dim]  [bold]{card.get('lemma', '')}[/bold] "
+            f"[dim]({card.get('part_of_speech', '')})[/dim]"
+        )
+        if card.get("context_sentence"):
+            console.print(f"  [italic dim]{card['context_sentence']}[/italic dim]")
+
+        rating = _prompt_rating()
+        if rating is None:
+            break
+
+        result = _run(
+            lambda c, cid=card["id"], r=rating: c.submit_review(user_vocabulary_id=cid, rating=r)
+        )
+        reviewed += 1
+        console.print(
+            f"  [green]✓ {RATINGS[rating]}[/green] — next review "
+            f"{_fmt_dt(result.get('next_review'))}\n"
+        )
+
+    console.print(f"[bold]Reviewed {reviewed} of {len(cards)} card(s).[/bold]")
+
+
+# ── `glossa lang` sub-app ─────────────────────────────────────────────────────
+
+lang_app = typer.Typer(
+    help="Show or set your default learning language (for `add` and `set`).",
+    invoke_without_command=True,
+    no_args_is_help=False,
+)
+app.add_typer(lang_app, name="lang")
+
+
+@lang_app.callback(invoke_without_command=True)
+def _lang_default(ctx: typer.Context) -> None:
+    """Show the effective default language and where it comes from.
+
+    Called when `glossa lang` is invoked without a subcommand. With a
+    subcommand (`set` / `unset`) Typer dispatches there instead.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    flag_value: str | None = None  # no per-call flag in this context
+    env_value = os.environ.get("GLOSSA_LANG", "").strip() or None
+    file_value = config.get_default_language()
+    effective = config.resolve_language(flag_value)
+
+    if effective is None:
+        console.print(
+            "[dim]No default language set.[/dim]\n"
+            "Glossa will infer the language from your account when you run "
+            "[bold]glossa add[/bold] / [bold]glossa set[/bold]. If you have "
+            "multiple enabled, set a default:\n"
+            "  [bold]glossa lang set <code>[/bold]   # e.g. en, fr, pt-PT"
+        )
+        return
+
+    source = "GLOSSA_LANG env" if env_value else (
+        "~/.config/glossa/config.json" if file_value else "fallback"
+    )
+    console.print(f"Default language: [bold]{effective}[/bold]  [dim]({source})[/dim]")
+    if env_value and file_value and env_value != file_value:
+        console.print(
+            f"[dim]Note: GLOSSA_LANG={env_value} overrides the persisted "
+            f"default ({file_value}).[/dim]"
+        )
+
+
+@lang_app.command("set")
+def lang_set(
+    code: str = typer.Argument(..., help="Language code: en, fr, or pt-PT."),
+) -> None:
+    """Persist a default learning language to ~/.config/glossa/config.json."""
+    _validate_lang(code)
+    config.set_default_language(code)
+    console.print(
+        f"[green]✓ Default language set to [bold]{code}[/bold].[/green] "
+        f"[dim](~/.config/glossa/config.json)[/dim]"
+    )
+
+
+@lang_app.command("unset")
+def lang_unset() -> None:
+    """Remove the persisted default language."""
+    if config.unset_default_language():
+        console.print("[green]✓ Default language removed.[/green]")
+    else:
+        console.print("[dim]No default language was set.[/dim]")
+
+
+# ── Output helpers ─────────────────────────────────────────────────────────────
+
+
+def _prompt_rating() -> int | None:
+    """Prompt until a valid 1–4 rating or 'q' is entered. Returns None on quit."""
+    while True:
+        raw = typer.prompt("  Rating (1-4, q to quit)").strip().lower()
+        if raw in ("q", "quit"):
+            return None
+        if raw.isdigit() and int(raw) in RATINGS:
+            return int(raw)
+        err_console.print("  [red]Enter 1, 2, 3, 4, or q.[/red]")
+
+
+def _print_vocab_item(item: dict, action: str) -> None:
+    bits = [f"[green]{action}[/green] [bold]{item.get('lemma', '')}[/bold]"]
+    if item.get("part_of_speech"):
+        bits.append(f"({item['part_of_speech']})")
+    bits.append(f"→ status [bold]{item.get('status', '')}[/bold]")
+    if item.get("cefr_level"):
+        bits.append(f"· CEFR {item['cefr_level']}")
+    console.print(" ".join(bits))
+    if item.get("next_review"):
+        console.print(f"[dim]Next review: {_fmt_dt(item['next_review'])}[/dim]")
+
+
+def _fmt_dt(value: str | None) -> str:
+    if not value:
+        return "—"
+    # ISO timestamps render fine trimmed to the minute.
+    return value.replace("T", " ")[:16]
+
+
+def main() -> None:
+    """Console-script entry point."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

glossa_cli/client.py

@@ -0,0 +1,184 @@
+"""Thin httpx client for the Glossa REST API.
+
+Vendored from ``backend/glossa_mcp/client.py`` and extended with the vocabulary
+and review endpoints the CLI needs. Authentication is resolved in this order:
+
+1. ``GLOSSA_API_TOKEN`` env var — a static ``glossa_*`` API token generated in
+   Glossa Settings → Tokens. Useful for scripting / CI.
+2. OAuth 2.0 device-code flow (RFC 8628) — the first time there are no stored
+   credentials, a URL is printed to stderr so the user can approve in a browser.
+   Subsequent runs load the saved access/refresh tokens from
+   ``~/.config/glossa/credentials.json`` and refresh automatically.
+
+Set ``GLOSSA_API_URL`` (default ``https://api.glossa.pro``) to point at a
+different instance (e.g. ``http://localhost:8000`` for local dev).
+"""
+
+import os
+from typing import Any
+
+import httpx
+
+from glossa_cli.auth import AuthError, ensure_token
+
+DEFAULT_TIMEOUT_SECONDS = 30
+DEFAULT_BASE_URL = "https://api.glossa.pro"
+
+
+class GlossaApiError(Exception):
+    """Raised when the API responds with an error status.
+
+    ``detail`` preserves the parsed body of FastAPI's ``detail`` field — either
+    a string (most errors) or a dict (structured errors like
+    ``{"error": "multiple_languages", "enabled": [...]}``). The CLI inspects
+    the dict shape to render actionable messages.
+    """
+
+    def __init__(self, status_code: int, detail: "str | dict") -> None:
+        super().__init__(f"HTTP {status_code}: {detail}")
+        self.status_code = status_code
+        self.detail = detail
+
+
+class GlossaClient:
+    """Async client that authenticates with a static API token **or** OAuth.
+
+    Call ``await client.ensure_auth()`` before the first request — or just
+    use the async context manager which calls it for you.
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        token: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        self.base_url = (base_url or os.environ.get("GLOSSA_API_URL", DEFAULT_BASE_URL)).rstrip("/")
+        self._static_token = token or os.environ.get("GLOSSA_API_TOKEN", "")
+        self._timeout = timeout
+        self._client: httpx.AsyncClient | None = None
+
+    async def ensure_auth(self) -> None:
+        """Resolve the bearer token (static env var or OAuth) and open the httpx client."""
+        if self._client is not None:
+            return  # already initialised
+
+        if not self.base_url:
+            raise RuntimeError(
+                "GLOSSA_API_URL is not set. Export it (e.g. "
+                "https://api.glossa.pro, or http://localhost:8000 for local dev)."
+            )
+
+        if self._static_token:
+            bearer = self._static_token
+        else:
+            try:
+                bearer = await ensure_token(self.base_url)
+            except AuthError as exc:
+                raise RuntimeError(str(exc)) from exc
+
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=self._timeout,
+            headers={"Authorization": f"Bearer {bearer}"},
+        )
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> "GlossaClient":
+        await self.ensure_auth()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def _request(
+        self, method: str, path: str, json: dict | None = None
+    ) -> Any:
+        if self._client is None:
+            await self.ensure_auth()
+        resp = await self._client.request(method, path, json=json)  # type: ignore[union-attr]
+        if resp.is_success:
+            if resp.status_code == 204 or not resp.content:
+                return None
+            return resp.json()
+        try:
+            payload = resp.json()
+            detail = payload.get("detail", resp.text) if isinstance(payload, dict) else resp.text
+        except ValueError:
+            detail = resp.text or resp.reason_phrase
+        # Preserve structured detail (dict) as-is so the CLI can branch on it;
+        # fall back to a string for plain-text errors.
+        raise GlossaApiError(
+            resp.status_code, detail if isinstance(detail, dict) else str(detail)
+        )
+
+    # ── Text analysis ─────────────────────────────────────────────────────────
+
+    async def analyze_text(
+        self, content: str, language_code: str | None = None
+    ) -> Any:
+        body: dict[str, Any] = {"content": content}
+        if language_code is not None:
+            body["language_code"] = language_code
+        return await self._request("POST", "/api/articles/analyze", body)
+
+    # ── Vocabulary ──────────────────────────────────────────────────────────────
+
+    async def add_word(
+        self,
+        lemma: str,
+        language_code: str | None = None,
+        part_of_speech: str | None = None,
+        status: str = "learning",
+        translation: str | None = None,
+    ) -> Any:
+        body: dict[str, Any] = {"lemma": lemma, "status": status}
+        if language_code is not None:
+            body["language_code"] = language_code
+        if part_of_speech is not None:
+            body["part_of_speech"] = part_of_speech
+        if translation is not None:
+            body["user_translation"] = translation
+        return await self._request("POST", "/api/vocabulary/add", body)
+
+    async def list_vocabulary(
+        self, status: str | None = None, language_code: str | None = None
+    ) -> Any:
+        params: dict[str, str] = {}
+        if status is not None:
+            params["status"] = status
+        if language_code is not None:
+            params["language_code"] = language_code
+        query = ("?" + "&".join(f"{k}={v}" for k, v in params.items())) if params else ""
+        return await self._request("GET", f"/api/vocabulary{query}")
+
+    async def update_status(
+        self,
+        lexical_entry_id: int,
+        status: str,
+        user_translation: str | None = None,
+    ) -> Any:
+        body: dict[str, Any] = {
+            "lexical_entry_id": lexical_entry_id,
+            "status": status,
+        }
+        if user_translation is not None:
+            body["user_translation"] = user_translation
+        return await self._request("POST", "/api/vocabulary/update", body)
+
+    async def list_learning_words(self, language_code: str | None = None) -> Any:
+        params = f"?language_code={language_code}" if language_code else ""
+        return await self._request("GET", f"/api/extension/learning-words{params}")
+
+    # ── Reviews (FSRS) ────────────────────────────────────────────────────────
+
+    async def reviews_due(self, limit: int = 50) -> Any:
+        return await self._request("GET", f"/api/reviews/due?limit={limit}")
+
+    async def submit_review(self, user_vocabulary_id: int, rating: int) -> Any:
+        body = {"user_vocabulary_id": user_vocabulary_id, "rating": rating}
+        return await self._request("POST", "/api/reviews/submit", body)