tisit-cli 0.1.0__py3-none-any.whl

tisit_cli/__init__.py

@@ -0,0 +1,2 @@
+"""TISIT CLI — terminal-native client for the TISIT learning platform."""
+__version__ = "0.1.0"

tisit_cli/auth.py

@@ -0,0 +1,54 @@
+"""Token storage — keyring with file fallback."""
+import os
+import stat
+from pathlib import Path
+
+SERVICE_NAME = "tisit-cli"
+TOKEN_FILE = Path.home() / ".tisit" / "token"
+
+
+def store_token(token: str) -> None:
+    """Store API token securely."""
+    try:
+        import keyring
+        keyring.set_password(SERVICE_NAME, "api_token", token)
+        # Clean up file if migrating to keyring
+        if TOKEN_FILE.exists():
+            TOKEN_FILE.unlink()
+        return
+    except Exception:
+        pass
+    # File fallback
+    TOKEN_FILE.parent.mkdir(parents=True, exist_ok=True)
+    TOKEN_FILE.write_text(token)
+    os.chmod(TOKEN_FILE, stat.S_IRUSR | stat.S_IWUSR)
+
+
+def get_token() -> str | None:
+    """Retrieve stored API token."""
+    try:
+        import keyring
+        token = keyring.get_password(SERVICE_NAME, "api_token")
+        if token:
+            return token
+    except Exception:
+        pass
+    if TOKEN_FILE.exists():
+        return TOKEN_FILE.read_text().strip()
+    return None
+
+
+def delete_token() -> None:
+    """Remove stored API token."""
+    try:
+        import keyring
+        keyring.delete_password(SERVICE_NAME, "api_token")
+    except Exception:
+        pass
+    if TOKEN_FILE.exists():
+        TOKEN_FILE.unlink()
+
+
+def validate_token_format(token: str) -> bool:
+    """Check that the token has the expected tsk_ prefix and length."""
+    return token.startswith("tsk_") and len(token) >= 20

tisit_cli/client.py

@@ -0,0 +1,392 @@
+"""HTTP API client — all communication with the TISIT server goes through here."""
+import httpx
+
+from . import __version__
+from .exceptions import APIError, AuthenticationError, NotFoundError
+
+
+class TisitClient:
+    """Synchronous HTTP client for the TISIT API v1."""
+
+    def __init__(self, base_url: str, token: str):
+        self._base = base_url.rstrip("/") + "/api/v1"
+        self._http = httpx.Client(
+            base_url=self._base,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+                "User-Agent": f"tisit-cli/{__version__}",
+            },
+            timeout=30.0,
+        )
+
+    def close(self):
+        self._http.close()
+
+    # ── internal ──────────────────────────────────────────────────────
+
+    @staticmethod
+    def _parse_json(resp):
+        """Safely parse JSON from response, returning {} on empty/invalid."""
+        if not resp.content or not resp.content.strip():
+            return {}
+        try:
+            return resp.json()
+        except Exception:
+            return {}
+
+    def _request(self, method, path, **kwargs):
+        """Issue request and unwrap the API envelope."""
+        try:
+            resp = self._http.request(method, path, **kwargs)
+        except httpx.ConnectError:
+            raise APIError(
+                "Cannot reach the TISIT server. Is it running?",
+                status_code=0,
+            )
+        except httpx.TimeoutException:
+            raise APIError("Request timed out", status_code=0)
+
+        if resp.status_code == 401:
+            raise AuthenticationError(
+                "Token expired or invalid. Run: tisit login"
+            )
+        if resp.status_code == 403:
+            raise AuthenticationError(
+                "Insufficient permissions for this operation"
+            )
+        if resp.status_code == 404:
+            body = self._parse_json(resp)
+            msg = body.get("error", {}).get("message", "Resource not found")
+            raise NotFoundError(msg)
+
+        body = self._parse_json(resp)
+
+        if not body.get("success", False):
+            err = body.get("error", {})
+            raise APIError(
+                err.get("message", f"API error (HTTP {resp.status_code})"),
+                status_code=resp.status_code,
+                detail=err.get("errors"),
+            )
+
+        return body.get("data"), body.get("meta")
+
+    # ── public methods ────────────────────────────────────────────────
+
+    def status(self):
+        data, _ = self._request("GET", "/status")
+        return data
+
+    def list_notes(self, *, q=None, category=None, domain=None,
+                   sort="created_at", order="desc", page=1, per_page=20):
+        params = {"sort": sort, "order": order, "page": page,
+                  "per_page": per_page}
+        if q:
+            params["q"] = q
+        if category:
+            params["category"] = category
+        if domain:
+            params["domain"] = domain
+        data, meta = self._request("GET", "/notes", params=params)
+        return data, meta
+
+    def get_note(self, note_id: int):
+        data, _ = self._request("GET", f"/notes/{note_id}")
+        return data
+
+    def create_note(self, term: str, context: str):
+        data, _ = self._request(
+            "POST", "/notes", json={"term": term, "context": context}
+        )
+        return data
+
+    def delete_note(self, note_id: int):
+        data, _ = self._request("DELETE", f"/notes/{note_id}")
+        return data
+
+    # ── papers ─────────────────────────────────────────────────────
+
+    def list_papers(self, *, q=None, sort="uploaded_at", order="desc",
+                    page=1, per_page=20):
+        params = {"sort": sort, "order": order, "page": page,
+                  "per_page": per_page}
+        if q:
+            params["q"] = q
+        data, meta = self._request("GET", "/papers", params=params)
+        return data, meta
+
+    def get_paper(self, paper_id: int):
+        data, _ = self._request("GET", f"/papers/{paper_id}")
+        return data
+
+    def add_paper(self, url: str, *, title=None, authors=None):
+        payload = {"url": url}
+        if title:
+            payload["title"] = title
+        if authors:
+            payload["authors"] = authors
+        data, _ = self._request("POST", "/papers", json=payload)
+        return data
+
+    def delete_paper(self, paper_id: int):
+        data, _ = self._request("DELETE", f"/papers/{paper_id}")
+        return data
+
+    # ── articles ───────────────────────────────────────────────────
+
+    def list_articles(self, *, q=None, sort="fetched_at", order="desc",
+                      page=1, per_page=20):
+        params = {"sort": sort, "order": order, "page": page,
+                  "per_page": per_page}
+        if q:
+            params["q"] = q
+        data, meta = self._request("GET", "/articles", params=params)
+        return data, meta
+
+    def get_article(self, article_id: int):
+        data, _ = self._request("GET", f"/articles/{article_id}")
+        return data
+
+    def add_article(self, url: str):
+        data, _ = self._request("POST", "/articles", json={"url": url})
+        return data
+
+    def delete_article(self, article_id: int):
+        data, _ = self._request("DELETE", f"/articles/{article_id}")
+        return data
+
+    # ── videos ─────────────────────────────────────────────────────
+
+    def list_videos(self, *, q=None, sort="created_at", order="desc",
+                    page=1, per_page=20):
+        params = {"sort": sort, "order": order, "page": page,
+                  "per_page": per_page}
+        if q:
+            params["q"] = q
+        data, meta = self._request("GET", "/videos", params=params)
+        return data, meta
+
+    def get_video(self, video_id: int):
+        data, _ = self._request("GET", f"/videos/{video_id}")
+        return data
+
+    def add_video(self, url: str):
+        data, _ = self._request("POST", "/videos", json={"url": url})
+        return data
+
+    def delete_video(self, video_id: int):
+        data, _ = self._request("DELETE", f"/videos/{video_id}")
+        return data
+
+    # ── tweets ─────────────────────────────────────────────────────
+
+    def list_tweets(self, *, q=None, sort="created_at", order="desc",
+                    page=1, per_page=20):
+        params = {"sort": sort, "order": order, "page": page,
+                  "per_page": per_page}
+        if q:
+            params["q"] = q
+        data, meta = self._request("GET", "/tweets", params=params)
+        return data, meta
+
+    def get_tweet(self, tweet_id: int):
+        data, _ = self._request("GET", f"/tweets/{tweet_id}")
+        return data
+
+    def add_tweet(self, url: str):
+        data, _ = self._request("POST", "/tweets", json={"url": url})
+        return data
+
+    def delete_tweet(self, tweet_id: int):
+        data, _ = self._request("DELETE", f"/tweets/{tweet_id}")
+        return data
+
+    # ── books ──────────────────────────────────────────────────────
+
+    def search_books(self, *, title="", author="", limit=10):
+        params = {"limit": limit}
+        if title:
+            params["title"] = title
+        if author:
+            params["author"] = author
+        data, meta = self._request("GET", "/books/search", params=params)
+        return data, meta
+
+    def list_books(self, *, q=None, sort="added_at", order="desc",
+                   page=1, per_page=20):
+        params = {"sort": sort, "order": order, "page": page,
+                  "per_page": per_page}
+        if q:
+            params["q"] = q
+        data, meta = self._request("GET", "/books", params=params)
+        return data, meta
+
+    def get_book(self, book_id: int):
+        data, _ = self._request("GET", f"/books/{book_id}")
+        return data
+
+    def add_book(self, title: str, *, authors=None, isbn_13=None,
+                 google_books_id=None, description=None):
+        payload = {"title": title}
+        if authors:
+            payload["authors"] = authors
+        if isbn_13:
+            payload["isbn_13"] = isbn_13
+        if google_books_id:
+            payload["google_books_id"] = google_books_id
+        if description:
+            payload["description"] = description
+        data, _ = self._request("POST", "/books", json=payload)
+        return data
+
+    def delete_book(self, book_id: int):
+        data, _ = self._request("DELETE", f"/books/{book_id}")
+        return data
+
+    # ── podcasts ───────────────────────────────────────────────────
+
+    def list_podcasts(self, *, q=None, sort="created_at", order="desc",
+                      page=1, per_page=20):
+        params = {"sort": sort, "order": order, "page": page,
+                  "per_page": per_page}
+        if q:
+            params["q"] = q
+        data, meta = self._request("GET", "/podcasts", params=params)
+        return data, meta
+
+    def get_podcast(self, podcast_id: int):
+        data, _ = self._request("GET", f"/podcasts/{podcast_id}")
+        return data
+
+    def add_podcast(self, url: str):
+        data, _ = self._request("POST", "/podcasts", json={"url": url})
+        return data
+
+    def delete_podcast(self, podcast_id: int):
+        data, _ = self._request("DELETE", f"/podcasts/{podcast_id}")
+        return data
+
+    # ── patents ────────────────────────────────────────────────────
+
+    def list_patents(self, *, q=None, sort="fetched_at", order="desc",
+                     page=1, per_page=20):
+        params = {"sort": sort, "order": order, "page": page,
+                  "per_page": per_page}
+        if q:
+            params["q"] = q
+        data, meta = self._request("GET", "/patents", params=params)
+        return data, meta
+
+    def get_patent(self, patent_id: int):
+        data, _ = self._request("GET", f"/patents/{patent_id}")
+        return data
+
+    def add_patent(self, *, url=None, patent_number=None):
+        payload = {}
+        if url:
+            payload["url"] = url
+        if patent_number:
+            payload["patent_number"] = patent_number
+        data, _ = self._request("POST", "/patents", json=payload)
+        return data
+
+    def delete_patent(self, patent_id: int):
+        data, _ = self._request("DELETE", f"/patents/{patent_id}")
+        return data
+
+    # ── chat ──────────────────────────────────────────────────────
+
+    def chat_ask(self, question: str, *, session_id=None):
+        payload = {"question": question}
+        if session_id:
+            payload["session_id"] = session_id
+        data, _ = self._request("POST", "/chat/ask", json=payload)
+        return data
+
+    # ── radar sweep ────────────────────────────────────────────────
+
+    def radar_status(self):
+        data, _ = self._request("GET", "/radar/status")
+        return data
+
+    def list_watch_topics(self):
+        data, _ = self._request("GET", "/radar/topics")
+        return data
+
+    def create_watch_topic(self, topic: str, keywords=None):
+        payload = {"topic": topic}
+        if keywords:
+            payload["keywords"] = keywords
+        data, _ = self._request("POST", "/radar/topics", json=payload)
+        return data
+
+    def delete_watch_topic(self, topic_id: int):
+        data, _ = self._request("DELETE", f"/radar/topics/{topic_id}")
+        return data
+
+    def get_sweep_run(self, run_id: int):
+        data, _ = self._request("GET", f"/radar/runs/{run_id}")
+        return data
+
+    def accept_source(self, source_id: int):
+        data, _ = self._request("POST", f"/radar/sources/{source_id}/accept")
+        return data
+
+    def ignore_source(self, source_id: int):
+        data, _ = self._request("POST", f"/radar/sources/{source_id}/ignore")
+        return data
+
+    # ── knowledge graph ────────────────────────────────────────────
+
+    def graph_stats(self):
+        data, _ = self._request("GET", "/graph/stats")
+        return data
+
+    def graph_neighbors(self, term: str, *, limit=10):
+        data, meta = self._request(
+            "GET", f"/graph/neighbors/{term}", params={"limit": limit}
+        )
+        return data, meta
+
+    def graph_paths(self, source: str, target: str, *, max_depth=3):
+        data, meta = self._request(
+            "POST", "/graph/paths",
+            json={"source": source, "target": target, "max_depth": max_depth},
+        )
+        return data, meta
+
+    # ── focus mode ─────────────────────────────────────────────────
+
+    def list_focus_bubbles(self):
+        data, _ = self._request("GET", "/focus")
+        return data
+
+    def get_focus_bubble(self, bubble_id: int):
+        data, _ = self._request("GET", f"/focus/{bubble_id}")
+        return data
+
+    def create_focus_bubble(self, topic: str):
+        data, _ = self._request("POST", "/focus", json={"topic": topic})
+        return data
+
+    def delete_focus_bubble(self, bubble_id: int):
+        data, _ = self._request("DELETE", f"/focus/{bubble_id}")
+        return data
+
+    def add_focus_concept(self, bubble_id: int, name: str, *,
+                          definition=None, category="term"):
+        payload = {"name": name, "category": category}
+        if definition:
+            payload["definition"] = definition
+        data, _ = self._request(
+            "POST", f"/focus/{bubble_id}/concepts", json=payload
+        )
+        return data
+
+    # ── search ────────────────────────────────────────────────────
+
+    def search(self, query: str, *, type="all", limit=10):
+        params = {"q": query, "type": type, "limit": limit}
+        data, meta = self._request("GET", "/search", params=params)
+        return data, meta

tisit_cli/commands/article_commands.py

@@ -0,0 +1,132 @@
+"""Article commands: add, list, view, delete."""
+import json
+from typing import Optional
+
+import typer
+
+from ..auth import get_token
+from ..client import TisitClient
+from ..config import Config
+from ..display import (
+    print_error, print_article_detail, print_article_table,
+    print_success,
+)
+from ..exceptions import AuthenticationError, APIError, NotFoundError
+
+article_app = typer.Typer(help="Manage your web articles")
+
+
+def _get_client() -> TisitClient:
+    token = get_token()
+    if not token:
+        print_error("Not logged in. Run: tisit login")
+        raise typer.Exit(code=1)
+    cfg = Config()
+    return TisitClient(cfg.api_url, token)
+
+
+@article_app.command("list")
+def article_list(
+    query: Optional[str] = typer.Option(None, "--query", "-q", help="Search title or domain"),
+    sort: str = typer.Option("fetched_at", "--sort", "-s", help="Sort by: fetched_at, title"),
+    order: str = typer.Option("desc", "--order", "-o", help="asc or desc"),
+    page: int = typer.Option(1, "--page", "-p"),
+    per_page: int = typer.Option(20, "--per-page"),
+    output_json: bool = typer.Option(False, "--json", help="JSON output"),
+):
+    """List your articles."""
+    client = _get_client()
+    try:
+        articles, meta = client.list_articles(
+            q=query, sort=sort, order=order, page=page, per_page=per_page,
+        )
+    except (AuthenticationError, APIError) as exc:
+        print_error(str(exc))
+        raise typer.Exit(code=1)
+    finally:
+        client.close()
+
+    if output_json:
+        typer.echo(json.dumps({"data": articles, "meta": meta}, indent=2, default=str))
+    else:
+        if not articles:
+            print_error("No articles found.")
+        else:
+            print_article_table(articles, meta)
+
+
+@article_app.command("view")
+def article_view(
+    article_id: int = typer.Argument(..., help="Article ID"),
+    output_json: bool = typer.Option(False, "--json", help="JSON output"),
+):
+    """View an article in detail."""
+    client = _get_client()
+    try:
+        article = client.get_article(article_id)
+    except NotFoundError:
+        print_error(f"Article {article_id} not found.")
+        raise typer.Exit(code=1)
+    except (AuthenticationError, APIError) as exc:
+        print_error(str(exc))
+        raise typer.Exit(code=1)
+    finally:
+        client.close()
+
+    if output_json:
+        typer.echo(json.dumps(article, indent=2, default=str))
+    else:
+        print_article_detail(article)
+
+
+@article_app.command("add")
+def article_add(
+    url: str = typer.Argument(..., help="Article URL"),
+    output_json: bool = typer.Option(False, "--json", help="JSON output"),
+):
+    """Add an article by URL (async — queued for processing)."""
+    client = _get_client()
+    try:
+        data = client.add_article(url)
+    except (AuthenticationError, APIError) as exc:
+        print_error(str(exc))
+        raise typer.Exit(code=1)
+    finally:
+        client.close()
+
+    if output_json:
+        typer.echo(json.dumps(data, indent=2, default=str))
+    else:
+        if data.get("is_duplicate"):
+            print_success(f"Article already exists (ID: {data['article_id']}).")
+        else:
+            print_success(
+                f"Article queued for processing (ID: {data['article_id']}).\n"
+                f"  Check status with: tisit article view {data['article_id']}"
+            )
+
+
+@article_app.command("delete")
+def article_delete(
+    article_id: int = typer.Argument(..., help="Article ID to delete"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+):
+    """Delete an article."""
+    if not yes:
+        confirm = typer.confirm(f"Delete article {article_id}?")
+        if not confirm:
+            raise typer.Abort()
+
+    client = _get_client()
+    try:
+        client.delete_article(article_id)
+    except NotFoundError:
+        print_error(f"Article {article_id} not found.")
+        raise typer.Exit(code=1)
+    except (AuthenticationError, APIError) as exc:
+        print_error(str(exc))
+        raise typer.Exit(code=1)
+    finally:
+        client.close()
+
+    print_success(f"Article {article_id} deleted.")

tisit_cli/commands/auth_commands.py

@@ -0,0 +1,91 @@
+"""Auth commands: login, logout, whoami."""
+import json
+import typer
+
+from ..auth import store_token, get_token, delete_token, validate_token_format
+from ..client import TisitClient
+from ..config import Config
+from ..display import print_success, print_error, print_info
+from ..exceptions import APIError, AuthenticationError
+
+
+def login(
+    token: str = typer.Option(
+        None, "--token", "-t",
+        help="API token (prompted securely if omitted)",
+    ),
+    api_url: str = typer.Option(
+        None, "--api-url", "-u",
+        help="Server URL (saved to config)",
+    ),
+):
+    """Authenticate with your TISIT API token."""
+    if not token:
+        token = typer.prompt("API token", hide_input=True)
+
+    token = token.strip()
+    if not validate_token_format(token):
+        print_error("Invalid token format. Tokens start with 'tsk_'.")
+        raise typer.Exit(code=1)
+
+    cfg = Config()
+    if api_url:
+        cfg.set("api_url", api_url.rstrip("/"))
+        cfg.save()
+
+    # Verify token against the server
+    client = TisitClient(cfg.api_url, token)
+    try:
+        client.status()
+    except (AuthenticationError, APIError) as exc:
+        print_error(f"Token verification failed: {exc}")
+        raise typer.Exit(code=1)
+    finally:
+        client.close()
+
+    store_token(token)
+    print_success(f"Logged in to {cfg.api_url}")
+
+
+def logout():
+    """Clear stored credentials."""
+    delete_token()
+    print_success("Logged out.")
+
+
+def whoami(
+    output_json: bool = typer.Option(False, "--json", help="JSON output"),
+):
+    """Show current authentication status."""
+    token = get_token()
+    if not token:
+        print_error("Not logged in. Run: tisit login")
+        raise typer.Exit(code=1)
+
+    cfg = Config()
+    client = TisitClient(cfg.api_url, token)
+    try:
+        data = client.status()
+        connected = True
+    except Exception:
+        data = {}
+        connected = False
+    finally:
+        client.close()
+
+    prefix = token[:12] + "..."
+
+    if output_json:
+        typer.echo(json.dumps({
+            "token_prefix": prefix,
+            "api_url": cfg.api_url,
+            "connected": connected,
+            "server_status": data.get("status") if data else None,
+        }, indent=2))
+    else:
+        print_info(f"Token:  {prefix}")
+        print_info(f"Server: {cfg.api_url}")
+        if connected:
+            print_success(f"Status: connected (server {data.get('status', 'ok')})")
+        else:
+            print_error("Status: cannot reach server")