loktar-cli 0.1.0__tar.gz

loktar_cli-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: loktar-cli
+Version: 0.1.0
+Summary: CLI and AI agent client for LOKTAR — query 2100+ curated AI tools across 86+ tablets
+Author-email: Loktar Team <info@loktar.cc>
+License: MIT
+Project-URL: Homepage, https://loktar.cc
+Keywords: cli,ai-tools,agents,mcp,loktar
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: rich>=13.0.0
+
+# LOKTAR CLI (`loktar`)
+
+A super efficient, scriptable command-line interface and AI agent client for **LOKTAR** (https://loktar.cc).
+
+Allows both human developers and autonomous AI agents (Claude Code, Antigravity, Aider, Cursor, etc.) to query, search, and inspect 86+ tablets and 2100+ AI tools with minimum token usage and zero prompt overhead.
+
+## Installation
+
+```bash
+pip install --upgrade lockthard-cli
+```
+
+Or run without installing:
+
+```bash
+pipx run lockthard-cli --help
+```
+
+## Quick Start
+
+### 1. Authentication
+Get your API key from [loktar.cc](https://loktar.cc).
+
+- **For AI Agents & CI/CD:**
+  ```bash
+  export LOKTAR_API_KEY="lk_your_token_here"
+  ```
+- **Interactive Browser Login (Humans):**
+  ```bash
+  loktar login
+  ```
+- **Manual Login:**
+  ```bash
+  loktar login --token "lk_your_token_here"
+  ```
+
+### 2. Commands
+
+```bash
+# Ping service
+loktar ping
+
+# Search tools (returns concise table)
+loktar search "ocr"
+
+# Search tools in raw JSON (for agents / jq)
+loktar -j search "ocr"
+
+# List all tablets
+loktar tablets list
+
+# Inspect a specific tablet
+loktar tablets get ocr
+
+# Inspect tool details
+loktar tools get "Chandra OCR"
+
+# Display CLI agent guide
+loktar guide
+
+# Display full agent skill
+loktar skill
+```
+
+## Options
+
+- `--json` / `-j`: Output raw JSON without Rich styling.
+- `--url` / `-u`: Override base server URL (default: `https://loktar.cc`).
+- `--token` / `-t`: Override API token.
+
+## License
+
+MIT License

loktar_cli-0.1.0/README.md

@@ -0,0 +1,73 @@
+# LOKTAR CLI (`loktar`)
+
+A super efficient, scriptable command-line interface and AI agent client for **LOKTAR** (https://loktar.cc).
+
+Allows both human developers and autonomous AI agents (Claude Code, Antigravity, Aider, Cursor, etc.) to query, search, and inspect 86+ tablets and 2100+ AI tools with minimum token usage and zero prompt overhead.
+
+## Installation
+
+```bash
+pip install --upgrade lockthard-cli
+```
+
+Or run without installing:
+
+```bash
+pipx run lockthard-cli --help
+```
+
+## Quick Start
+
+### 1. Authentication
+Get your API key from [loktar.cc](https://loktar.cc).
+
+- **For AI Agents & CI/CD:**
+  ```bash
+  export LOKTAR_API_KEY="lk_your_token_here"
+  ```
+- **Interactive Browser Login (Humans):**
+  ```bash
+  loktar login
+  ```
+- **Manual Login:**
+  ```bash
+  loktar login --token "lk_your_token_here"
+  ```
+
+### 2. Commands
+
+```bash
+# Ping service
+loktar ping
+
+# Search tools (returns concise table)
+loktar search "ocr"
+
+# Search tools in raw JSON (for agents / jq)
+loktar -j search "ocr"
+
+# List all tablets
+loktar tablets list
+
+# Inspect a specific tablet
+loktar tablets get ocr
+
+# Inspect tool details
+loktar tools get "Chandra OCR"
+
+# Display CLI agent guide
+loktar guide
+
+# Display full agent skill
+loktar skill
+```
+
+## Options
+
+- `--json` / `-j`: Output raw JSON without Rich styling.
+- `--url` / `-u`: Override base server URL (default: `https://loktar.cc`).
+- `--token` / `-t`: Override API token.
+
+## License
+
+MIT License

loktar_cli-0.1.0/loktar_cli/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: loktar
+description: "LOKTAR CLI — query 2100+ curated AI tools across 86+ tablets. Search, browse tablets, get tool details, and investigate repos. Designed for both humans and AI agents."
+version: 0.2.8
+metadata:
+  hermes:
+    tags: [loktar, tools, ai, search, tablets, mcp]
+    homepage: https://loktar.cc
+---
+
+# LOKTAR CLI
+
+CLI para consultar el directorio de herramientas IA de LOKTAR (2100+ herramientas, 86+ tablets). Diseñada para humanos (tablas Rich) y agentes IA (JSON limpio).
+
+## Autenticación
+
+```bash
+# Opción 1: Variable de entorno (recomendado para agentes)
+export LOKTAR_API_KEY="lk_tu_token"
+
+# Opción 2: Login con token
+loktar login --token lk_tu_token
+
+# Opción 3: Login interactivo (abre navegador)
+loktar login
+```
+
+Token guardado en `~/.loktar/credentials.json` con permisos 0600.
+
+## Flag JSON (`-j` / `--json`)
+
+Para agentes IA: **siempre usa `-j`** para recibir JSON limpio sin formato ANSI.
+
+El flag funciona tanto a nivel global como en cualquier subcommand:
+
+```bash
+loktar -j tablets list                    # ✅ global
+loktar tablets list -j                    # ✅ en subcommand
+loktar -j tablets get vector-knowledge-base  # ✅
+loktar tablets get vector-knowledge-base -j  # ✅
+```
+
+## Comandos
+
+| Comando | Descripción |
+|---|---|
+| `loktar ping` | Verificar conexión y autenticación |
+| `loktar -j search "<query>"` | Buscar herramientas por palabra clave |
+| `loktar -j tablets list` | Listar todos los tablets disponibles |
+| `loktar -j tablets get <tablet_id>` | Ver herramientas de un tablet |
+| `loktar -j tools get "<tool_id>"` | Detalles de una herramienta específica |
+| `loktar -j cli-tools` | Listar herramientas CLI dedicadas |
+| `loktar guide` | Guía rápida para agentes |
+| `loktar skill` | Muestra esta SKILL.md completa |
+
+## Estructura de un Tablet
+
+Cada tablet es una colección curada de herramientas agrupadas por temática. Al obtener un tablet (`loktar -j tablets get <id>`), recibes:
+
+```json
+{
+  "id": "vector-knowledge-base",
+  "title": "Vector Knowledge Base",
+  "toolCount": 41,
+  "tools": [
+    {
+      "name": "Graphify",
+      "description": "Transforma un proyecto en un knowledge graph...",
+      "url": "https://github.com/safishamsi/graphify",
+      "section": "General",
+      "snippetsCount": 1
+    }
+  ]
+}
+```
+
+### Cómo interpretar las herramientas
+
+- **`section`**: Categoría que agrupa la herramienta. **La sección YA es contexto** — si una herramienta está en "Memoria Y Contexto Para Agentes", eso ya indica su dominio.
+- **`description`**: Descripción textual (puede estar vacía si el nombre + sección + URL son suficientes).
+- **`url`**: Enlace al repositorio o sitio web. **El agente debe investigar esta URL** para obtener más detalles (leer README, verificar instalación, etc.).
+- **`snippetsCount`**: Número de snippets de código o instrucciones adicionales disponibles vía `tools get`.
+
+### Ejemplo: interpretación correcta
+
+```
+Herramienta: "LightRAG"
+Sección:     "RAG" (o "General")
+URL:         https://github.com/HKUDS/LightRAG
+Descripción: (vacía)
+```
+
+**Interpretación correcta:** Es un sistema RAG. La sección indica que es de la categoría RAG. La URL apunta a GitHub donde el agente puede leer el README para entender qué hace.
+
+**Interpretación incorrecta:** ❌ "Herramienta sin descripción, está incompleta."
+
+## Flujo de trabajo recomendado para agentes
+
+1. `loktar ping` — verificar auth
+2. `loktar -j tablets list` — ver tablets disponibles
+3. `loktar -j tablets get <id>` — explorar herramientas de un tablet relevante
+4. Para cada herramienta interesante: **ir al repo/URL y leer documentación**
+5. `loktar -j tools get "<nombre>"` — detalles específicos con snippets si se necesitan
+
+## Ejemplos de uso
+
+```bash
+# Buscar herramientas de OCR
+loktar -j search "ocr"
+
+# Ver todo el tablet de cybersecurity
+loktar -j tablets get cybersecurity
+
+# Ver detalles de una herramienta específica
+loktar -j tools get "Graphify"
+
+# Listar herramientas CLI
+loktar -j cli-tools
+
+# Verificar que todo funciona
+loktar ping
+```

loktar_cli-0.1.0/loktar_cli/__init__.py

@@ -0,0 +1,5 @@
+"""
+LOKTAR CLI - Command Line Interface and Agent Client for LOKTAR.
+"""
+
+__version__ = "0.2.9"

loktar_cli-0.1.0/loktar_cli/auth.py

@@ -0,0 +1,159 @@
+import http.server
+import socket
+import socketserver
+import urllib.parse
+import webbrowser
+from typing import Tuple, Optional, Dict, Any
+from .config import save_credentials, clear_credentials
+
+
+class OAuthCallbackHandler(http.server.BaseHTTPRequestHandler):
+    """Temporary HTTP handler to capture the token callback from browser authentication."""
+
+    received_token: Optional[str] = None
+    received_email: Optional[str] = None
+    error_message: Optional[str] = None
+
+    def log_message(self, format, *args):
+        # Silence default HTTP server logging
+        pass
+
+    def do_GET(self):
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path in ("/callback", "/"):
+            query = urllib.parse.parse_qs(parsed.query)
+            token = query.get("token", [None])[0]
+            email = query.get("email", [None])[0]
+            error = query.get("error", [None])[0]
+
+            if error:
+                OAuthCallbackHandler.error_message = error
+                self._send_response_html(
+                    status=400,
+                    title="Error de Autenticación",
+                    body=f"<p style='color: red;'>Error durante el inicio de sesión: {error}</p>"
+                )
+            elif token:
+                OAuthCallbackHandler.received_token = token
+                OAuthCallbackHandler.received_email = email
+                self._send_response_html(
+                    status=200,
+                    title="¡Autenticación Exitosa!",
+                    body="""
+                    <h2 style='color: #10B981;'>¡Autenticación Exitosa!</h2>
+                    <p>La CLI de <strong>LOKTAR</strong> ha sido conectada correctamente a tu cuenta.</p>
+                    <p>Ya puedes cerrar esta ventana y regresar a tu terminal.</p>
+                    """
+                )
+            else:
+                self._send_response_html(
+                    status=400,
+                    title="Falta Token",
+                    body="<p style='color: red;'>No se recibió ningún token de autenticación.</p>"
+                )
+        else:
+            self.send_error(404, "Not Found")
+
+    def _send_response_html(self, status: int, title: str, body: str):
+        self.send_response(status)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.end_headers()
+
+        html = f"""<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>{title}</title>
+    <style>
+        body {{
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+            background: #0d1117;
+            color: #c9d1d9;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            height: 100vh;
+            margin: 0;
+        }}
+        .card {{
+            background: #161b22;
+            border: 1px solid #30363d;
+            border-radius: 12px;
+            padding: 32px;
+            max-width: 420px;
+            text-align: center;
+            box-shadow: 0 10px 25px rgba(0,0,0,0.5);
+        }}
+    </style>
+</head>
+<body>
+    <div class="card">
+        {body}
+    </div>
+</body>
+</html>
+"""
+        self.wfile.write(html.encode("utf-8"))
+
+
+def find_free_port(start_port: int = 8989) -> int:
+    """Find an available port starting from start_port."""
+    for port in range(start_port, start_port + 20):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            try:
+                s.bind(("127.0.0.1", port))
+                return port
+            except OSError:
+                continue
+    return start_port
+
+
+def perform_browser_login(api_url: str, timeout_seconds: int = 120) -> Tuple[bool, str]:
+    """
+    Launch local server, open browser to loktar.cc/cli-auth, and capture token.
+    """
+    port = find_free_port(8989)
+    callback_url = f"http://127.0.0.1:{port}/callback"
+    auth_url = f"{api_url.rstrip('/')}/cli-auth?callback={urllib.parse.quote(callback_url)}"
+
+    OAuthCallbackHandler.received_token = None
+    OAuthCallbackHandler.received_email = None
+    OAuthCallbackHandler.error_message = None
+
+    class ReusableTCPServer(socketserver.TCPServer):
+        allow_reuse_address = True
+
+    try:
+        httpd = ReusableTCPServer(("127.0.0.1", port), OAuthCallbackHandler)
+        httpd.timeout = 1.0
+    except Exception as e:
+        return False, f"No se pudo iniciar el servidor local en el puerto {port}: {e}"
+
+    print(f"Abriendo el navegador para autenticar en LOKTAR...")
+    print(f"URL: {auth_url}\n")
+    try:
+        webbrowser.open(auth_url)
+    except Exception:
+        print("No se pudo abrir el navegador automáticamente. Por favor abre la URL manualmente.")
+
+    import time
+    start_time = time.time()
+
+    while time.time() - start_time < timeout_seconds:
+        httpd.handle_request()
+        if OAuthCallbackHandler.received_token:
+            token = OAuthCallbackHandler.received_token
+            email = OAuthCallbackHandler.received_email
+            httpd.server_close()
+
+            # Save credentials
+            save_credentials(api_key=token, email=email, api_url=api_url)
+            user_str = f" como {email}" if email else ""
+            return True, f"¡Autenticado correctamente{user_str}!"
+
+        if OAuthCallbackHandler.error_message:
+            httpd.server_close()
+            return False, f"Error devuelto por la autenticación: {OAuthCallbackHandler.error_message}"
+
+    httpd.server_close()
+    return False, "Tiempo de espera agotado (timeout) esperando la autorización en el navegador."

loktar_cli-0.1.0/loktar_cli/cli.py

@@ -0,0 +1,242 @@
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+import click
+
+from . import __version__
+from .config import resolve_token, resolve_api_url, save_credentials, clear_credentials
+from .auth import perform_browser_login
+from .client import LoktarClient, LoktarError
+from .formatters import (
+    output_data,
+    print_ping_result,
+    print_tablets_list,
+    print_search_results,
+    print_tablet_content,
+    print_tool_details,
+    print_cli_tools,
+    print_agent_guide,
+    HAS_RICH,
+    console,
+)
+from rich.markdown import Markdown
+
+
+def _handle_error(err: Exception):
+    """Print clean error message without traceback."""
+    click.secho(f"Error: {err}", fg="red", err=True)
+    sys.exit(1)
+
+
+def _get_as_json(ctx: click.Context, local_flag: bool) -> bool:
+    """Merge global --json with local subcommand --json flag."""
+    return ctx.obj.get("as_json", False) or local_flag
+
+
+@click.group(invoke_without_command=False,
+             epilog="Primer uso: loktar skill  |  Para agentes: loktar -j skill")
+@click.option("--url", "-u", default=None, help="Base URL del servidor LOKTAR (default: https://loktar.cc).")
+@click.option("--token", "-t", default=None, help="API Key / Token de autenticación (lk_...).")
+@click.option("--json", "-j", "as_json", is_flag=True, help="Salida en JSON bruto (ideal para scripts y agentes).")
+@click.version_option(version=__version__, prog_name="loktar")
+@click.pass_context
+def cli(ctx: click.Context, url: Optional[str], token: Optional[str], as_json: bool):
+    """LOKTAR CLI - Cliente super eficiente de herramientas IA para humanos y agentes.
+
+Primer uso: loktar skill | Para agentes: loktar -j skill
+"""
+    resolved_url = resolve_api_url(url)
+    resolved_token = resolve_token(token)
+
+    ctx.ensure_object(dict)
+    ctx.obj["url"] = resolved_url
+    ctx.obj["token"] = resolved_token
+    ctx.obj["as_json"] = as_json
+    ctx.obj["client"] = LoktarClient(base_url=resolved_url, token=resolved_token)
+
+
+@cli.command()
+@click.option("--json", "-j", "as_json_local", is_flag=True, default=False,
+              help="Salida en JSON bruto (ideal para scripts y agentes).")
+@click.pass_context
+def ping(ctx: click.Context, as_json_local: bool):
+    """Verifica la conectividad con el servidor de LOKTAR y el estado del token."""
+    client: LoktarClient = ctx.obj["client"]
+    as_json = _get_as_json(ctx, as_json_local)
+    try:
+        res = client.ping()
+        print_ping_result(res, as_json=as_json)
+    except LoktarError as e:
+        _handle_error(e)
+
+
+@cli.command()
+@click.option("--token", "-t", help="API Key directa (lk_...) para guardar sin interacción.")
+@click.option("--manual", "-m", is_flag=True, help="Modo interactivo en consola (sin abrir navegador).")
+@click.pass_context
+def login(ctx: click.Context, token: Optional[str], manual: bool):
+    """Inicia sesión en LOKTAR (Browser OAuth, Token o Interactivo)."""
+    api_url = ctx.obj["url"]
+
+    # 1. Direct token via flag
+    if token and token.strip():
+        save_credentials(api_key=token.strip(), api_url=api_url)
+        click.secho("✓ API Key guardada correctamente en ~/.loktar/credentials.json", fg="green")
+        return
+
+    # 2. Manual prompt via flag
+    if manual:
+        token_input = click.prompt("Pega tu API Key de LOKTAR (lk_...)", hide_input=True)
+        if not token_input or not token_input.strip():
+            _handle_error(LoktarError("Token vacío."))
+        save_credentials(api_key=token_input.strip(), api_url=api_url)
+        click.secho("✓ API Key guardada correctamente en ~/.loktar/credentials.json", fg="green")
+        return
+
+    # 3. Interactive Browser Login
+    click.echo(f"Iniciando flujo de autenticación para {api_url}...")
+    success, msg = perform_browser_login(api_url)
+    if success:
+        click.secho(f"✓ {msg}", fg="green")
+    else:
+        click.secho(f"✗ {msg}", fg="yellow")
+        click.echo("Puedes autenticarte manualmente con: loktar login --token lk_tu_token")
+
+
+@cli.command()
+def logout():
+    """Cierra la sesión y elimina las credenciales locales."""
+    if clear_credentials():
+        click.secho("✓ Sesión cerrada y credenciales eliminadas (~/.loktar/credentials.json).", fg="green")
+    else:
+        click.echo("No había ninguna sesión activa guardada.")
+
+
+@cli.command()
+@click.option("--json", "-j", "as_json_local", is_flag=True, default=False,
+              help="Salida en JSON bruto (ideal para scripts y agentes).")
+@click.argument("query")
+@click.option("--tablet", "-t", help="Filtrar por ID de tablet específica.")
+@click.option("--limit", "-l", default=20, type=int, help="Límite de resultados (default: 20).")
+@click.pass_context
+def search(ctx: click.Context, as_json_local: bool, query: str, tablet: Optional[str], limit: int):
+    """Busca herramientas por palabra clave en LOKTAR."""
+    client: LoktarClient = ctx.obj["client"]
+    as_json = _get_as_json(ctx, as_json_local)
+    try:
+        results = client.search_tools(query=query, tablet_id=tablet, limit=limit)
+        print_search_results(query, results, as_json=as_json)
+    except LoktarError as e:
+        _handle_error(e)
+
+
+@cli.group()
+def tablets():
+    """Comandos para explorar las tablets de LOKTAR."""
+    pass
+
+
+@tablets.command(name="list")
+@click.option("--json", "-j", "as_json_local", is_flag=True, default=False,
+              help="Salida en JSON bruto (ideal para scripts y agentes).")
+@click.option("--query", "-q", help="Filtrar tablets por título o categoría.")
+@click.pass_context
+def list_tablets_cmd(ctx: click.Context, as_json_local: bool, query: Optional[str]):
+    """Lista los 61+ tablets y categorías disponibles."""
+    client: LoktarClient = ctx.obj["client"]
+    as_json = _get_as_json(ctx, as_json_local)
+    try:
+        res = client.list_tablets(query=query)
+        print_tablets_list(res, as_json=as_json)
+    except LoktarError as e:
+        _handle_error(e)
+
+
+@tablets.command(name="get")
+@click.option("--json", "-j", "as_json_local", is_flag=True, default=False,
+              help="Salida en JSON bruto (ideal para scripts y agentes).")
+@click.argument("tablet_id")
+@click.option("--limit", "-l", type=int, help="Límite de herramientas a devolver.")
+@click.pass_context
+def get_tablet_cmd(ctx: click.Context, as_json_local: bool, tablet_id: str, limit: Optional[int]):
+    """Obtiene el contenido completo de un tablet por su ID (ej. ocr, open-source)."""
+    client: LoktarClient = ctx.obj["client"]
+    as_json = _get_as_json(ctx, as_json_local)
+    try:
+        res = client.get_tablet(tablet_id=tablet_id, limit=limit)
+        print_tablet_content(res, as_json=as_json)
+    except LoktarError as e:
+        _handle_error(e)
+
+
+@cli.group()
+def tools():
+    """Comandos para inspeccionar herramientas individuales."""
+    pass
+
+
+@tools.command(name="get")
+@click.option("--json", "-j", "as_json_local", is_flag=True, default=False,
+              help="Salida en JSON bruto (ideal para scripts y agentes).")
+@click.argument("tool_id")
+@click.pass_context
+def get_tool_cmd(ctx: click.Context, as_json_local: bool, tool_id: str):
+    """Obtiene los detalles y comandos recomendados de una herramienta específica."""
+    client: LoktarClient = ctx.obj["client"]
+    as_json = _get_as_json(ctx, as_json_local)
+    try:
+        res = client.get_tool_details(tool_id=tool_id)
+        print_tool_details(res, as_json=as_json)
+    except LoktarError as e:
+        _handle_error(e)
+
+
+@cli.command(name="cli-tools")
+@click.option("--json", "-j", "as_json_local", is_flag=True, default=False,
+              help="Salida en JSON bruto (ideal para scripts y agentes).")
+@click.pass_context
+def cli_tools_cmd(ctx: click.Context, as_json_local: bool):
+    """Lista las herramientas especializadas de línea de comandos en LOKTAR."""
+    client: LoktarClient = ctx.obj["client"]
+    as_json = _get_as_json(ctx, as_json_local)
+    try:
+        res = client.get_cli_tools()
+        print_cli_tools(res, as_json=as_json)
+    except LoktarError as e:
+        _handle_error(e)
+
+
+@cli.command()
+def guide():
+    """Muestra la guía rápida de la CLI optimizada para Agentes de IA."""
+    print_agent_guide()
+
+
+@cli.command()
+@click.pass_context
+def skill(ctx: click.Context):
+    """Muestra la SKILL.md integrada del paquete para que un Agente de IA la importe."""
+    try:
+        skill_path = Path(__file__).parent / "SKILL.md"
+        if not skill_path.exists():
+            raise FileNotFoundError(f"SKILL.md no encontrada en {skill_path}")
+        content = skill_path.read_text(encoding="utf-8")
+
+        if ctx.obj.get("as_json"):
+            print(json.dumps({"skill": content}, ensure_ascii=False))
+        else:
+            if HAS_RICH and console:
+                console.print(Markdown(content))
+            else:
+                print(content)
+    except Exception as e:
+        _handle_error(LoktarError(f"No se pudo leer SKILL.md: {e}"))
+
+
+def main():
+    cli(obj={})
+
+
+if __name__ == "__main__":
+    main()