glossa-cli 0.1.1__tar.gz

glossa_cli-0.1.1/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: glossa-cli
+Version: 0.1.1
+Summary: Command-line client for Glossa — analyze text and manage your vocabulary from the terminal
+Project-URL: Homepage, https://glossa.pro
+Project-URL: Repository, https://github.com/artemiy-rodionov/glossa
+Project-URL: Issues, https://github.com/artemiy-rodionov/glossa/issues
+Author-email: Artemiy Rodionov <artemiy.rodionov@gmail.com>
+Keywords: cli,flashcards,fsrs,glossa,language-learning,vocabulary
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# glossa-cli
+
+A standalone command-line client for [Glossa](https://glossa.pro) — analyze text
+and manage your vocabulary from the terminal.
+
+## Install (one command)
+
+```sh
+pipx install glossa-cli      # recommended — isolated install
+# or:
+pip install glossa-cli
+```
+
+Both put the `glossa` command on your PATH. No `uv` or source checkout required.
+
+## Sign in (OAuth — no token to copy)
+
+Run `glossa login` first. It opens a browser to authorise you; after you
+approve, your tokens are cached in `~/.config/glossa/credentials.json` and
+refreshed automatically — you won't need to sign in again.
+
+```sh
+glossa login          # opens a browser; prints an auth URL to approve
+glossa login --force  # clear the cached sign-in and authorise again
+```
+
+> **Self-hosted / local dev:** point the CLI at your instance with
+> `export GLOSSA_API_URL=http://localhost:8000` (defaults to
+> `https://api.glossa.pro`).
+>
+> **CI / scripting:** skip the browser flow by exporting a static token from
+> Glossa → Settings → Tokens: `export GLOSSA_API_TOKEN=glossa_xxx`.
+
+## Usage
+
+```sh
+# Analyze text (arg, --file, or stdin)
+echo "The serendipitous discovery broke the ice." | glossa analyze --lang en
+glossa analyze --file article.txt
+glossa analyze "a short sentence" --json
+
+# Add a word or phrase
+glossa add serendipity --lang en --status learning
+glossa add "break the ice" --lang en -t "сломать лёд"
+
+# Change a word's state (upserts by lemma; --id targets one sense)
+glossa set serendipity known --lang en
+glossa set --id 1234 saved
+
+# List your vocabulary
+glossa list --status learning
+glossa list --lang fr --json
+
+# Interactive FSRS review session
+glossa review --lang en
+```

glossa_cli-0.1.1/README.md

@@ -0,0 +1,56 @@
+# glossa-cli
+
+A standalone command-line client for [Glossa](https://glossa.pro) — analyze text
+and manage your vocabulary from the terminal.
+
+## Install (one command)
+
+```sh
+pipx install glossa-cli      # recommended — isolated install
+# or:
+pip install glossa-cli
+```
+
+Both put the `glossa` command on your PATH. No `uv` or source checkout required.
+
+## Sign in (OAuth — no token to copy)
+
+Run `glossa login` first. It opens a browser to authorise you; after you
+approve, your tokens are cached in `~/.config/glossa/credentials.json` and
+refreshed automatically — you won't need to sign in again.
+
+```sh
+glossa login          # opens a browser; prints an auth URL to approve
+glossa login --force  # clear the cached sign-in and authorise again
+```
+
+> **Self-hosted / local dev:** point the CLI at your instance with
+> `export GLOSSA_API_URL=http://localhost:8000` (defaults to
+> `https://api.glossa.pro`).
+>
+> **CI / scripting:** skip the browser flow by exporting a static token from
+> Glossa → Settings → Tokens: `export GLOSSA_API_TOKEN=glossa_xxx`.
+
+## Usage
+
+```sh
+# Analyze text (arg, --file, or stdin)
+echo "The serendipitous discovery broke the ice." | glossa analyze --lang en
+glossa analyze --file article.txt
+glossa analyze "a short sentence" --json
+
+# Add a word or phrase
+glossa add serendipity --lang en --status learning
+glossa add "break the ice" --lang en -t "сломать лёд"
+
+# Change a word's state (upserts by lemma; --id targets one sense)
+glossa set serendipity known --lang en
+glossa set --id 1234 saved
+
+# List your vocabulary
+glossa list --status learning
+glossa list --lang fr --json
+
+# Interactive FSRS review session
+glossa review --lang en
+```

glossa_cli-0.1.1/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "glossa-cli"
+version = "0.1.1"
+description = "Command-line client for Glossa — analyze text and manage your vocabulary from the terminal"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Artemiy Rodionov", email = "artemiy.rodionov@gmail.com" }]
+keywords = ["glossa", "vocabulary", "language-learning", "cli", "flashcards", "fsrs"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Education",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "httpx>=0.28",
+    "typer>=0.12",
+    "rich>=13",
+]
+
+[project.urls]
+Homepage = "https://glossa.pro"
+Repository = "https://github.com/artemiy-rodionov/glossa"
+Issues = "https://github.com/artemiy-rodionov/glossa/issues"
+
+[project.scripts]
+# Once published to PyPI, users install with a single command — no uv or
+# source checkout required:
+#   pipx install glossa-cli      (recommended, isolated)
+#   pip install glossa-cli
+# This puts the `glossa` command on PATH.
+glossa = "glossa_cli.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/glossa_cli"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.25",
+    "ruff>=0.8",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM"]

glossa_cli-0.1.1/src/glossa_cli/__init__.py

@@ -0,0 +1,7 @@
+"""Glossa CLI — a standalone terminal client for the Glossa REST API.
+
+Talks to the API over HTTP using the same auth as the MCP server
+(``GLOSSA_API_TOKEN`` static token or OAuth device-code flow). Install with::
+
+    uv tool install glossa-cli      # or: pipx install glossa-cli / uvx glossa-cli
+"""

glossa_cli-0.1.1/src/glossa_cli/auth.py

@@ -0,0 +1,227 @@
+"""OAuth 2.0 Device-Code flow + credential storage for the Glossa CLI.
+
+Vendored from ``backend/glossa_mcp/auth.py`` so the CLI ships as a standalone,
+lightweight package (httpx + stdlib only) without depending on the heavy
+``glossa-backend`` distribution.
+
+Design:
+- Credentials are stored in ``~/.config/glossa/credentials.json`` (shared with
+  the MCP client — a token approved once works for both).
+- When a valid access token exists it's used directly.
+- When the access token has expired the refresh token is used to get a new pair.
+- When there are no credentials at all, the device-code flow is initiated:
+    1. POST /api/oauth/device_authorization → get device_code + user_code
+    2. Print verification_uri_complete to stderr so the user can approve it.
+    3. Poll /api/oauth/token every ``interval`` seconds until approved, denied
+       or the device code expires.
+    4. Save the resulting access + refresh tokens to disk.
+
+Only ``ensure_token(base_url)`` is the public entry-point — it returns a valid
+Bearer token string or raises ``AuthError`` (fatal, surfaced to the user).
+"""
+
+import asyncio
+import json
+import sys
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import httpx
+
+# ── Configuration ─────────────────────────────────────────────────────────────
+
+CREDENTIALS_PATH = Path.home() / ".config" / "glossa" / "credentials.json"
+POLL_MAX_SECONDS = 600  # 10 min — matches backend DEVICE_CODE_TTL
+DEFAULT_POLL_INTERVAL = 5  # seconds between /token poll attempts
+
+
+# ── Data ─────────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class Credentials:
+    access_token: str
+    refresh_token: str
+    expires_at: float  # Unix timestamp when access_token expires
+    base_url: str
+
+    def access_expired(self) -> bool:
+        # Give a 30-second buffer so we refresh before the token actually expires.
+        return time.time() >= (self.expires_at - 30)
+
+
+# ── Storage ──────────────────────────────────────────────────────────────────
+
+
+def _load() -> Credentials | None:
+    if not CREDENTIALS_PATH.exists():
+        return None
+    try:
+        data = json.loads(CREDENTIALS_PATH.read_text())
+        return Credentials(**data)
+    except Exception:
+        return None
+
+
+def _save(creds: Credentials) -> None:
+    CREDENTIALS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CREDENTIALS_PATH.write_text(json.dumps(asdict(creds), indent=2))
+
+
+def _clear() -> None:
+    if CREDENTIALS_PATH.exists():
+        CREDENTIALS_PATH.unlink()
+
+
+def clear_credentials() -> bool:
+    """Remove any cached OAuth credentials. Returns True if a file was removed."""
+    existed = CREDENTIALS_PATH.exists()
+    _clear()
+    return existed
+
+
+# ── Errors ───────────────────────────────────────────────────────────────────
+
+
+class AuthError(Exception):
+    """Fatal auth failure — message is user-visible."""
+
+
+# ── OAuth HTTP helpers ────────────────────────────────────────────────────────
+
+
+async def _post(client: httpx.AsyncClient, path: str, body: dict) -> dict:
+    resp = await client.post(path, json=body)
+    try:
+        payload = resp.json()
+    except Exception:
+        payload = {}
+    if resp.is_success:
+        return payload
+    # Surface OAuth error_description if present
+    detail = payload.get("detail") or {}
+    if isinstance(detail, dict):
+        msg = detail.get("error_description") or detail.get("error") or str(payload)
+    elif isinstance(detail, str):
+        msg = detail
+    else:
+        msg = resp.text or resp.reason_phrase
+    raise httpx.HTTPStatusError(msg, request=resp.request, response=resp)
+
+
+async def _refresh(client: httpx.AsyncClient, refresh_token: str, base_url: str) -> Credentials:
+    data = await _post(client, "/api/oauth/token", {
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+    })
+    return Credentials(
+        access_token=data["access_token"],
+        refresh_token=data["refresh_token"],
+        expires_at=time.time() + data.get("expires_in", 3600),
+        base_url=base_url,
+    )
+
+
+# ── Device-code flow ─────────────────────────────────────────────────────────
+
+
+async def _device_flow(base_url: str) -> Credentials:
+    """Run the full RFC 8628 device-code flow interactively (via stderr)."""
+    async with httpx.AsyncClient(base_url=base_url, timeout=30) as client:
+        # 1 — Request codes
+        init = await _post(client, "/api/oauth/device_authorization", {})
+        device_code = init["device_code"]
+        user_code = init["user_code"]
+        verification_uri_complete = init["verification_uri_complete"]
+        interval = int(init.get("interval", DEFAULT_POLL_INTERVAL))
+
+        # 2 — Prompt user (stderr keeps stdout clean for piping / JSON output)
+        print(
+            f"\n{'─' * 60}\n"
+            f"  Glossa CLI — authorisation required\n\n"
+            f"  1. Open this URL in your browser:\n"
+            f"     {verification_uri_complete}\n\n"
+            f"  2. Code to confirm: {user_code}\n"
+            f"{'─' * 60}\n",
+            file=sys.stderr,
+            flush=True,
+        )
+
+        # 3 — Poll
+        deadline = time.time() + POLL_MAX_SECONDS
+        while time.time() < deadline:
+            await asyncio.sleep(interval)
+            try:
+                data = await _post(client, "/api/oauth/token", {
+                    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                    "device_code": device_code,
+                })
+                # Success
+                print("  ✓ Authorised — Glossa CLI is ready.\n", file=sys.stderr, flush=True)
+                return Credentials(
+                    access_token=data["access_token"],
+                    refresh_token=data["refresh_token"],
+                    expires_at=time.time() + data.get("expires_in", 3600),
+                    base_url=base_url,
+                )
+            except httpx.HTTPStatusError as exc:
+                # Parse the body that _post embeds in the exception message
+                try:
+                    body = exc.response.json()
+                    detail = body.get("detail", {})
+                    error_code = detail.get("error") if isinstance(detail, dict) else None
+                except Exception:
+                    error_code = None
+
+                if error_code == "authorization_pending":
+                    continue  # keep polling
+                if error_code == "slow_down":
+                    interval += 5
+                    continue
+                if error_code in ("access_denied", "expired_token", "invalid_grant"):
+                    # Upgrade path: surface the upgrade URL if present
+                    upgrade_url = (
+                        (detail or {}).get("upgrade_url") if isinstance(detail, dict) else None
+                    )
+                    if upgrade_url:
+                        raise AuthError(
+                            f"Glossa access requires a Pro subscription.\n"
+                            f"Upgrade at: {upgrade_url}"
+                        ) from exc
+                    raise AuthError(f"Authorisation denied ({error_code}).") from exc
+                # Unknown error — surface verbatim
+                raise AuthError(f"Token error: {exc}") from exc
+
+        raise AuthError("Authorisation timed out — please run the command again.")
+
+
+# ── Public entry-point ────────────────────────────────────────────────────────
+
+
+async def ensure_token(base_url: str) -> str:
+    """Return a valid Bearer token for *base_url*, refreshing or re-authorising as needed."""
+    creds = _load()
+
+    # Mismatched base_url (e.g. switched from prod to dev) — start fresh
+    if creds is not None and creds.base_url.rstrip("/") != base_url.rstrip("/"):
+        _clear()
+        creds = None
+
+    if creds is not None and not creds.access_expired():
+        return creds.access_token
+
+    if creds is not None and creds.refresh_token:
+        try:
+            async with httpx.AsyncClient(base_url=base_url, timeout=30) as client:
+                creds = await _refresh(client, creds.refresh_token, base_url)
+            _save(creds)
+            return creds.access_token
+        except Exception:
+            # Refresh failed (revoked / expired / downgraded) — full re-auth
+            _clear()
+
+    # No usable credentials — run device-code flow
+    creds = await _device_flow(base_url)
+    _save(creds)
+    return creds.access_token