cited-cli 0.3.2__py3-none-any.whl

cited_cli/__init__.py

@@ -0,0 +1 @@
+from cited_core import __version__ as __version__  # noqa: F401

cited_cli/__main__.py

@@ -0,0 +1,3 @@
+from cited_cli.app import main
+
+main()

cited_cli/api/client.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from cited_cli.utils.errors import CitedAPIError
+
+DEFAULT_TIMEOUT = 30.0
+LONG_TIMEOUT = 120.0
+
+
+class CitedClient:
+    def __init__(
+        self,
+        base_url: str,
+        token: str | None = None,
+        agent_api_key: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.agent_api_key = agent_api_key
+        headers: dict[str, str] = {
+            "Accept": "application/json",
+        }
+        cookies: dict[str, str] = {}
+        if token:
+            cookies["advgeo_session"] = token
+        if agent_api_key:
+            headers["X-Agent-API-Key"] = agent_api_key
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            follow_redirects=True,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> CitedClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def _handle_response(self, response: httpx.Response) -> Any:
+        if response.is_success:
+            if response.headers.get("content-type", "").startswith("application/json"):
+                return response.json()
+            return response.text
+        # Try to extract error message from JSON body
+        message = f"HTTP {response.status_code}"
+        error_code = None
+        try:
+            body = response.json()
+            if isinstance(body, dict):
+                message = str(body.get("detail", body.get("message", message)))
+                error_code = body.get("error_code")
+        except Exception:
+            message = response.text or message
+        raise CitedAPIError(response.status_code, str(message), error_code)
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        response = self._client.get(path, params=params)
+        return self._handle_response(response)
+
+    def post(
+        self,
+        path: str,
+        json: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> Any:
+        kwargs: dict[str, Any] = {}
+        if json is not None:
+            kwargs["json"] = json
+        if data is not None:
+            kwargs["data"] = data
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        response = self._client.post(path, **kwargs)
+        return self._handle_response(response)
+
+    def put(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        response = self._client.put(path, json=json or {})
+        return self._handle_response(response)
+
+    def patch(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        response = self._client.patch(path, json=json or {})
+        return self._handle_response(response)
+
+    def delete(self, path: str) -> Any:
+        response = self._client.delete(path)
+        return self._handle_response(response)
+
+    def post_raw(
+        self,
+        path: str,
+        json: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> httpx.Response:
+        """POST that returns the raw httpx.Response (for cookie extraction, etc.)."""
+        kwargs: dict[str, Any] = {}
+        if json is not None:
+            kwargs["json"] = json
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        return self._client.post(path, **kwargs)

cited_cli/api/endpoints.py

@@ -0,0 +1,88 @@
+# Auth
+LOGIN = "/auth/login"
+CLI_LOGIN = "/auth/cli-login"
+CLI_REGISTER = "/auth/cli-register"
+CLI_VERIFY_EMAIL = "/auth/cli-verify-email"
+CLI_OAUTH_START = "/auth/cli-oauth-start"
+LOGOUT = "/auth/logout"
+ME = "/auth/me"
+
+# System / Health
+ROOT = "/"
+HEALTH = "/health"
+HEALTH_READY = "/health/ready"
+HEALTH_LIVE = "/health/live"
+HEALTH_APIS = "/health/apis"
+
+# Business
+BUSINESSES = "/businesses"
+BUSINESS = "/businesses/{business_id}"
+BUSINESS_LOGO = "/businesses/{business_id}/logo"
+HEALTH_SCORES = "/businesses/{business_id}/health-scores"
+HEALTH_SCORES_BREAKDOWN = "/businesses/{business_id}/health-scores/breakdown"
+
+# Business Crawl
+CRAWL_DATA = "/businesses/{business_id}/crawl-data"
+CRAWL_START = "/businesses/{business_id}/crawl"
+CRAWL_CANCEL = "/businesses/{business_id}/crawl/cancel"
+
+# Named Audits (templates)
+NAMED_AUDITS = "/named-audits"
+NAMED_AUDIT = "/named-audits/{named_audit_id}"
+
+# Audit
+AUDIT_START = "/audit/start"
+AUDIT_STATUS = "/audit/{job_id}/status"
+AUDIT_RESULT = "/audit/{job_id}/result"
+AUDIT_DETAILS = "/audit/{job_id}/details"
+AUDIT_EXPORT_PDF = "/audit/{job_id}/export/pdf"
+AUDIT_HISTORY = "/audit/history"
+AUDIT_CANCEL = "/audit/{job_id}/cancel"
+AUDIT_DELETE = "/audit/{job_id}"
+AUDIT_PROVIDERS = "/audit/{job_id}/providers"
+
+# Recommendations
+RECOMMEND_START = "/recommendations/start"
+RECOMMEND_STATUS = "/recommendations/{job_id}/status"
+RECOMMEND_RESULT = "/recommendations/{job_id}/result"
+RECOMMEND_HISTORY = "/recommendations/audit/{audit_job_id}/history"
+RECOMMEND_EXPORT_PDF = "/recommendations/{job_id}/export/pdf"
+RECOMMEND_CANCEL = "/recommendations/{job_id}/cancel"
+RECOMMEND_DELETE = "/recommendations/{job_id}"
+
+# Solutions
+SOLUTION_REQUEST = "/solutions/request"
+SOLUTION_CREATE = "/solutions/create"
+SOLUTION_PRIORITY_ACTION = "/solutions/priority-action"
+SOLUTION_STATUS = "/solutions/{job_id}/status"
+SOLUTION_RESULT = "/solutions/{job_id}/result"
+SOLUTION_HISTORY = "/solutions/history"
+SOLUTION_CANCEL = "/solutions/{job_id}/cancel"
+SOLUTION_DELETE = "/solutions/{job_id}"
+
+# Business HQ
+HQ = "/businesses/{business_id}/hq"
+HQ_HEAVY = "/businesses/{business_id}/hq/heavy"
+HQ_PRIORITY = "/businesses/{business_id}/hq/priority"
+HQ_EXPORT_PDF = "/businesses/{business_id}/hq/export/pdf"
+HQ_RECOMPUTE = "/businesses/{business_id}/hq/recompute"
+PERSONAS = "/businesses/{business_id}/personas"
+PRODUCTS = "/businesses/{business_id}/products"
+BUYER_INTENTS = "/businesses/{business_id}/buyer-intents"
+AGENTIC_READINESS = "/businesses/{business_id}/agentic-readiness"
+TRUST_SIGNALS = "/businesses/{business_id}/trust-signals"
+
+# Analytics
+ANALYTICS_COMPARISON = "/analytics/audits/{audit_id}/comparison"
+ANALYTICS_SUMMARY = "/analytics/businesses/{business_id}/summary"
+ANALYTICS_TRENDS = "/analytics/businesses/{business_id}/trends"
+ANALYTICS_ADVANCED = "/analytics/businesses/{business_id}/advanced-scoring"
+
+# Agent Query API (v1)
+AGENT_ROOT = "/agent/v1"
+AGENT_BUSINESS = "/agent/v1/business/{business_id}"
+AGENT_FACTS = "/agent/v1/business/{business_id}/facts"
+AGENT_CLAIMS = "/agent/v1/business/{business_id}/claims"
+AGENT_COMPARISON = "/agent/v1/business/{business_id}/comparison"
+AGENT_SEMANTIC_HEALTH = "/agent/v1/business/{business_id}/semantic-health"
+AGENT_BUYER_FIT = "/agent/v1/query/buyer-fit"

cited_cli/app.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import sys
+from typing import Annotated
+
+import typer
+
+from cited_cli import __version__
+from cited_cli.commands.agent import agent_app
+from cited_cli.commands.analytics import analytics_app
+from cited_cli.commands.audit import audit_app
+from cited_cli.commands.auth import auth_app, do_login, do_logout, do_register
+from cited_cli.commands.business import business_app
+from cited_cli.commands.config_cmd import config_app
+from cited_cli.commands.hq import hq_app
+from cited_cli.commands.job import job_app
+from cited_cli.commands.mcp_cmd import mcp_app
+from cited_cli.commands.named_audit import named_audit_app
+from cited_cli.commands.recommend import recommend_app
+from cited_cli.commands.solution import solution_app
+from cited_cli.output.formatter import OutputContext, print_error, print_result
+from cited_cli.output.tables import render_kv
+from cited_cli.utils.errors import CitedAPIError, ExitCode, handle_api_error
+from cited_core.api import endpoints
+from cited_core.api.client import CitedClient
+from cited_core.config.manager import ConfigManager
+
+app = typer.Typer(
+    name="cited",
+    help="CLI for the Cited GEO platform.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+# Register nested subcommand groups
+audit_app.add_typer(named_audit_app, name="template")
+
+# Register subcommand groups
+app.add_typer(auth_app, name="auth")
+app.add_typer(config_app, name="config")
+app.add_typer(business_app, name="business")
+app.add_typer(audit_app, name="audit")
+app.add_typer(recommend_app, name="recommend")
+app.add_typer(solution_app, name="solution")
+app.add_typer(hq_app, name="hq")
+app.add_typer(analytics_app, name="analytics")
+app.add_typer(agent_app, name="agent")
+app.add_typer(job_app, name="job")
+app.add_typer(mcp_app, name="mcp")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        print(f"cited-cli {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main_callback(
+    ctx: typer.Context,
+    version: Annotated[
+        bool | None,
+        typer.Option("--version", "-V", help="Show version and exit", callback=_version_callback,
+                     is_eager=True),
+    ] = None,
+    json_output: Annotated[
+        bool, typer.Option("--json", "-j", help="Output as JSON")
+    ] = False,
+    text_output: Annotated[
+        bool, typer.Option("--text", "-t", help="Output as human-readable text (overrides config)")
+    ] = False,
+    env: Annotated[
+        str | None, typer.Option("--env", "-e", help="Target environment (dev, prod, local)")
+    ] = None,
+    profile: Annotated[
+        str | None, typer.Option("--profile", "-p", help="Config profile to use")
+    ] = None,
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help="Verbose output")
+    ] = False,
+    quiet: Annotated[
+        bool, typer.Option("--quiet", "-q", help="Minimal output")
+    ] = False,
+    no_color: Annotated[
+        bool, typer.Option("--no-color", help="Disable colored output")
+    ] = False,
+) -> None:
+    """Cited GEO platform CLI."""
+    # Auto-detect non-TTY for color
+    if not sys.stdout.isatty():
+        no_color = True
+
+    config = ConfigManager()
+    profile_name = profile or "default"
+
+    # Resolve output format: --json/--text flags take precedence, then config, then default (text)
+    if json_output:
+        use_json = True
+    elif text_output:
+        use_json = False
+    else:
+        use_json = config.get("output", profile_name) == "json"
+
+    output_ctx = OutputContext(
+        json_mode=use_json,
+        quiet=quiet,
+        no_color=no_color,
+    )
+
+    ctx.ensure_object(dict)
+    ctx.obj["output"] = output_ctx
+    ctx.obj["config"] = config
+    ctx.obj["profile"] = profile_name
+    ctx.obj["env_override"] = env
+    ctx.obj["verbose"] = verbose
+
+
+@app.command()
+def version(ctx: typer.Context) -> None:
+    """Show the CLI version."""
+    obj = ctx.obj or {}
+    out: OutputContext = obj.get("output", OutputContext())
+    print_result(
+        {"version": __version__, "name": "cited-cli"},
+        out,
+        human_formatter=lambda d, c: c.print(f"cited-cli {d['version']}"),
+    )
+
+
+@app.command()
+def status(ctx: typer.Context) -> None:
+    """Check API health."""
+    obj = ctx.obj or {}
+    out: OutputContext = obj.get("output", OutputContext())
+    cfg: ConfigManager = obj.get("config", ConfigManager())
+    profile = obj.get("profile", "default")
+    api_url = cfg.get_api_url(profile, obj.get("env_override"))
+    env = cfg.get_environment(profile, obj.get("env_override"))
+
+    client = CitedClient(base_url=api_url, timeout=10.0)
+    try:
+        data = client.get(endpoints.HEALTH_READY)
+        data["environment"] = env
+        data["api_url"] = api_url
+        print_result(
+            data,
+            out,
+            human_formatter=lambda d, c: render_kv("API Status", d, c),
+        )
+    except CitedAPIError as e:
+        handle_api_error(e, out.json_mode)
+    except Exception as e:
+        print_error(f"Cannot reach API at {api_url}: {e}", out)
+        raise typer.Exit(ExitCode.ERROR) from e
+    finally:
+        client.close()
+
+
+@app.command()
+def login(
+    ctx: typer.Context,
+    email: Annotated[str | None, typer.Option(help="Email address")] = None,
+    password: Annotated[
+        str | None, typer.Option(help="Password", hide_input=True)
+    ] = None,
+    provider: Annotated[
+        str | None,
+        typer.Option(help="OAuth provider: google, microsoft, github"),
+    ] = None,
+) -> None:
+    """Log in to Cited. Opens browser by default, or use --email for password login."""
+    do_login(ctx, email, password, provider)
+
+
+@app.command()
+def logout(ctx: typer.Context) -> None:
+    """Log out and clear stored credentials."""
+    do_logout(ctx)
+
+
+@app.command()
+def register(
+    ctx: typer.Context,
+    email: Annotated[str | None, typer.Option(help="Email address")] = None,
+    name: Annotated[str | None, typer.Option(help="Full name")] = None,
+    password: Annotated[
+        str | None, typer.Option(help="Password", hide_input=True)
+    ] = None,
+    provider: Annotated[
+        str | None,
+        typer.Option(help="OAuth provider: google, microsoft, github"),
+    ] = None,
+) -> None:
+    """Register a new Cited account. Opens browser or use --email."""
+    do_register(ctx, email, name, password, provider)
+
+
+def main() -> None:
+    app()

cited_cli/auth/oauth_server.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import html
+import socket
+import threading
+from functools import partial
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlparse
+
+_SUCCESS_HTML_TEMPLATE = """\
+<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Cited CLI</title>
+<style>body{{font-family:system-ui,sans-serif;display:flex;justify-content:center;
+align-items:center;height:100vh;margin:0;background:#f8f9fa;}}
+.card{{text-align:center;padding:2rem;max-width:600px;}}
+.token-section{{margin-top:1.5rem;text-align:left;}}
+.token-box{{background:#f1f5f9;border:1px solid #cbd5e1;border-radius:6px;
+padding:0.75rem;font-family:monospace;font-size:0.8rem;word-break:break-all;
+max-height:4rem;overflow-y:auto;}}
+.copy-btn{{margin-top:0.5rem;padding:0.4rem 1rem;background:#3b82f6;color:#fff;
+border:none;border-radius:4px;cursor:pointer;font-size:0.85rem;}}
+.copy-btn:hover{{background:#2563eb;}}
+summary{{cursor:pointer;color:#64748b;font-size:0.9rem;}}</style></head>
+<body><div class="card">
+<h1 style="color:#22c55e;">&#10003; Authentication successful</h1>
+<p>You can close this tab and return to your terminal.</p>
+<details class="token-section">
+<summary>Terminal not responding? Copy your token manually</summary>
+<p style="font-size:0.85rem;color:#475569;">
+If the CLI didn't detect the login, copy this token and paste it in your terminal.</p>
+<div class="token-box" id="token-text">{token}</div>
+<button class="copy-btn" onclick="
+var t=document.getElementById('token-text').textContent;
+navigator.clipboard.writeText(t).then(function(){{this.textContent='Copied!'}}.bind(this))
+">Copy token</button>
+</details>
+</div></body></html>
+"""
+
+_ERROR_HTML = """\
+<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Cited CLI</title>
+<style>body{font-family:system-ui,sans-serif;display:flex;justify-content:center;
+align-items:center;height:100vh;margin:0;background:#f8f9fa;}
+.card{text-align:center;padding:2rem;}</style></head>
+<body><div class="card">
+<h1 style="color:#ef4444;">Authentication failed</h1>
+<p>No token was received. Please try again.</p>
+</div></body></html>
+"""
+
+
+def _find_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        port: int = s.getsockname()[1]
+        return port
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    def __init__(  # type: ignore[no-untyped-def]
+        self, token_event: threading.Event, server_ref: OAuthCallbackServer, *args, **kwargs,
+    ):
+        self._token_event = token_event
+        self._server_ref = server_ref
+        super().__init__(*args, **kwargs)
+
+    def do_GET(self) -> None:  # noqa: N802
+        parsed = urlparse(self.path)
+        if parsed.path != "/callback":
+            self.send_error(404)
+            return
+
+        params = parse_qs(parsed.query)
+        token = params.get("token", [None])[0]
+
+        if token:
+            self._server_ref.token = token
+            success_html = _SUCCESS_HTML_TEMPLATE.format(token=html.escape(token))
+            self._send_html(200, success_html)
+            self._token_event.set()
+        else:
+            self._send_html(400, _ERROR_HTML)
+
+    def _send_html(self, code: int, html: str) -> None:
+        self.send_response(code)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.end_headers()
+        self.wfile.write(html.encode())
+
+    def log_message(self, format: str, *args: object) -> None:  # noqa: A002
+        pass  # Suppress request logging
+
+
+class OAuthCallbackServer:
+    """Temporary localhost server to receive OAuth callback with token."""
+
+    def __init__(self, timeout: float = 120.0) -> None:
+        self.token: str | None = None
+        self.port: int = _find_free_port()
+        self.redirect_uri = f"http://localhost:{self.port}/callback"
+        self._timeout = timeout
+        self._token_event = threading.Event()
+        self._server: HTTPServer | None = None
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        handler = partial(_CallbackHandler, self._token_event, self)
+        self._server = HTTPServer(("127.0.0.1", self.port), handler)
+        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+
+    def wait_for_token(self) -> str | None:
+        self._token_event.wait(timeout=self._timeout)
+        return self.token
+
+    def shutdown(self) -> None:
+        if self._server:
+            self._server.shutdown()
+        if self._thread:
+            self._thread.join(timeout=5)

cited_cli/auth/store.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import stat
+
+from cited_cli.config.constants import CONFIG_DIR, CREDENTIALS_FILE, KEYRING_SERVICE
+
+
+class TokenStore:
+    def __init__(self) -> None:
+        self._keyring_available: bool | None = None
+
+    def _has_keyring(self) -> bool:
+        if self._keyring_available is None:
+            try:
+                import keyring
+                from keyring.backends.fail import Keyring as FailKeyring
+
+                backend = keyring.get_keyring()
+                self._keyring_available = not isinstance(backend, FailKeyring)
+            except Exception:
+                self._keyring_available = False
+        return self._keyring_available
+
+    def save_token(self, env: str, token: str) -> None:
+        if self._has_keyring():
+            import keyring
+
+            keyring.set_password(KEYRING_SERVICE, f"token:{env}", token)
+        else:
+            self._save_file(env, token)
+
+    def get_token(self, env: str) -> str | None:
+        if self._has_keyring():
+            import keyring
+
+            return keyring.get_password(KEYRING_SERVICE, f"token:{env}")
+        return self._load_file(env)
+
+    def delete_token(self, env: str) -> None:
+        if self._has_keyring():
+            import keyring
+
+            with contextlib.suppress(keyring.errors.PasswordDeleteError):
+                keyring.delete_password(KEYRING_SERVICE, f"token:{env}")
+        else:
+            self._delete_file(env)
+
+    def has_token(self, env: str) -> bool:
+        return self.get_token(env) is not None
+
+    # --- file fallback ---
+
+    def _ensure_creds_file(self) -> dict[str, str]:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        if CREDENTIALS_FILE.exists():
+            with open(CREDENTIALS_FILE) as f:
+                data: dict[str, str] = json.load(f)
+                return data
+        return {}
+
+    def _write_creds(self, data: dict[str, str]) -> None:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        with open(CREDENTIALS_FILE, "w") as f:
+            json.dump(data, f, indent=2)
+        os.chmod(CREDENTIALS_FILE, stat.S_IRUSR | stat.S_IWUSR)
+
+    def _save_file(self, env: str, token: str) -> None:
+        data = self._ensure_creds_file()
+        data[env] = token
+        self._write_creds(data)
+
+    def _load_file(self, env: str) -> str | None:
+        data = self._ensure_creds_file()
+        return data.get(env)
+
+    def _delete_file(self, env: str) -> None:
+        data = self._ensure_creds_file()
+        if env in data:
+            del data[env]
+            self._write_creds(data)