theus-cli 0.1.0

package/README.md

@@ -0,0 +1,245 @@
+# THEUS
+
+**THEUS HECHO EN PERU**  
+**AD ASTRA PER ASPERA**  
+Dominio comercial: `theus.pe`
+
+Theus es un agente CLI local-first para programar, entender proyectos, levantar memoria de codigo, visualizar grafos y explorar bases de datos. El producto nace para que cada usuario conecte su propio modelo local o su propia API key, sin depender de una marca externa ni de un proveedor unico.
+
+Esto ya no es un documento de estudio ni una propuesta de rebrand. Este repositorio es la base del producto Theus.
+
+## Que hace Theus
+
+- Abre una sesion interactiva desde cualquier proyecto con `theus`.
+- Indexa el proyecto localmente para reducir contexto repetido y mejorar memoria.
+- Levanta una API local en `127.0.0.1` con estado, grafo y esquema de base de datos.
+- Abre un dashboard visual del proyecto con mapa neuronal, archivos, simbolos, entidades, base de datos y memoria.
+- Permite conectar modelos locales, endpoints OpenAI-compatible o proveedores BYOK.
+- Mantiene paquetes propios en `vendor/theus-packages/` para preparar exports SDK, tipos y stubs de producto.
+- Usa identidad Theus: `.theus`, variables `THEUS_*`, dominio `theus.pe` y copy en espanol primero.
+
+## Instalacion para usuarios
+
+Requisito de runtime: **Bun**. Theus se compila y se ejecuta con Bun (`cli.js` es
+un bundle con target `bun`, no corre bajo Node). Si no tienes Bun, cualquiera de
+las opciones de abajo lo instala por ti, o hazlo manualmente:
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+### Opcion A — npm (global)
+
+```bash
+npm install -g theus-cli
+theus --version
+```
+
+Uso normal:
+
+```bash
+cd /ruta/de/tu/proyecto
+theus
+```
+
+Ejecucion puntual sin instalar (descarga temporal):
+
+```bash
+npx theus-cli --help
+```
+
+> Nota: el paquete publica un unico bundle self-contained (`cli.js`) con shebang
+> `#!/usr/bin/env bun`. `npm install -g` crea el enlace `theus` apuntando a ese
+> bundle; necesitas Bun en el PATH para ejecutarlo.
+
+### Opcion B — instalador (curl | bash)
+
+Instala Bun si falta, clona el CLI, compila el bundle y enlaza `theus` en tu PATH:
+
+```bash
+curl -fsSL https://theus.pe/install.sh | bash
+```
+
+Variables opcionales del instalador: `THEUS_REPO_URL`, `THEUS_REF`, `THEUS_HOME`,
+`THEUS_BIN_DIR`. El script vive en `scripts/install.sh`.
+
+### Opcion C — desde el repositorio (desarrollo)
+
+```bash
+bun install
+bun run build        # genera cli.js self-contained
+./cli.js --version   # o: bun run dev
+```
+
+Para escribir `theus` desde cualquier proyecto durante el desarrollo, enlaza el
+bundle compilado:
+
+```bash
+ln -sf "$(pwd)/cli.js" /usr/local/bin/theus
+```
+
+## Conectar un modelo
+
+Theus lee primero variables `THEUS_*`. Puedes apuntar a Ollama, LM Studio, LiteLLM, OpenRouter, un gateway propio o cualquier servidor OpenAI-compatible.
+
+Ejemplo con endpoint local:
+
+```bash
+export THEUS_BASE_URL="http://127.0.0.1:11434/v1"
+export THEUS_MODEL="llama3.1"
+export THEUS_API_KEY="local"
+theus
+```
+
+Ejemplo con archivo de proveedores:
+
+```json
+{
+  "providers": [
+    {
+      "id": "ollama",
+      "adapter": "openai-compatible",
+      "enabled": true,
+      "options": {
+        "baseURL": "http://127.0.0.1:11434/v1",
+        "model": "llama3.1",
+        "apiKey": "local"
+      }
+    }
+  ],
+  "policy": {
+    "text": ["ollama"]
+  }
+}
+```
+
+Ruta esperada del archivo:
+
+```text
+~/.theus/providers.json
+```
+
+## Dashboard local
+
+Al iniciar Theus dentro de un proyecto, el servicio de inteligencia local:
+
+- recorre archivos relevantes,
+- extrae simbolos,
+- construye nodos y relaciones,
+- detecta esquemas SQL/Prisma,
+- guarda indice y memoria bajo `~/.theus/knowledge/`,
+- expone un dashboard local.
+
+Endpoints disponibles:
+
+```text
+/dashboard
+/api/health
+/api/status
+/api/graph
+/api/database
+/api/db
+/api/schema
+```
+
+## Login y cuenta Theus
+
+El flujo remoto usa la arquitectura OAuth heredada, pero servida por `theus.pe`.
+
+```text
+GET  https://theus.pe/cai/oauth/authorize
+POST https://theus.pe/v1/oauth/token
+GET  https://theus.pe/api/oauth/profile
+GET  https://theus.pe/api/oauth/theus_cli/roles
+POST https://theus.pe/api/oauth/theus_cli/create_api_key
+```
+
+Uso directo:
+
+```bash
+theus login
+```
+
+Ese comando abre `https://theus.pe/cai/oauth/authorize`, recibe el callback local, intercambia `code` por token OAuth y crea una API key Theus para configurar la terminal. La ruta de suscripcion dentro del CLI tambien apunta a `https://theus.pe/cai/oauth/authorize`; no debe abrir dominios externos como flujo principal de producto.
+
+Variables utiles:
+
+| Variable | Uso |
+| --- | --- |
+| `THEUS_BASE_URL` | URL base del proveedor OpenAI-compatible |
+| `THEUS_OPENAI_BASE_URL` | Alias compatible para proveedor OpenAI-compatible |
+| `THEUS_MODEL` | Modelo principal |
+| `THEUS_OPENAI_MODEL` | Alias compatible de modelo |
+| `THEUS_API_KEY` | API key del proveedor |
+| `THEUS_PROVIDER_ID` | Nombre visible del proveedor activo |
+| `THEUS_DISABLE_MAIN_PROVIDER=1` | Fuerza el motor de compatibilidad |
+| `THEUS_DISABLE_TOOLS=1` | Desactiva tool-calling para endpoints simples |
+| `THEUS_NO_PROJECT_INTELLIGENCE=1` | No levanta indice/API/dashboard |
+| `THEUS_NO_OPEN_DASHBOARD=1` | Levanta API sin abrir el navegador |
+| `PROJECT_API_PORT=65235` | Fija el puerto local |
+| `INDEX_MAX_FILES=2500` | Limite de archivos indexados |
+| `THEUS_ENABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1` | Opt-in para marketplace oficial |
+
+## Comandos principales
+
+| Comando | Proposito |
+| --- | --- |
+| `theus` | Inicia la sesion interactiva |
+| `theus -p "prompt"` | Ejecuta en modo no interactivo |
+| `theus --help` | Muestra ayuda |
+| `/help` | Ayuda dentro del REPL |
+| `/login` | Configuracion de acceso cuando se usa una cuenta remota |
+| `/model` | Seleccion de modelo |
+| `/mcp` | Servidores MCP |
+| `/permissions` | Permisos de herramientas |
+| `/init` | Inicializa documentacion de proyecto |
+
+El copy visible debe mantenerse en espanol primero. Cuando haga sentido, una etiqueta corta en ingles puede aparecer como apoyo: `Iniciar / Start`, `Base de datos / Database`, `Mapa neuronal / Neural map`.
+
+## Estructura importante
+
+```text
+bin/theus                         launcher local
+entrypoints/cli.tsx               entrada del CLI
+main.tsx                          entrada UI heredada, evitar editar en bloque
+screens/REPL.tsx                  REPL interactivo
+components/Theus/                 banner, menu, setup de proveedor
+services/api/theus.ts             router OpenAI-compatible y fallback
+services/projectIntelligence/     API local, dashboard, base de datos visual
+services/knowledge/               indice, memoria y grafo local
+vendor/theus-packages/            paquetes propios SDK/MCP
+types/theus-sdk.d.ts              tipos publicos base
+```
+
+## Calidad y verificacion
+
+Smoke tests recomendados:
+
+```bash
+./bin/theus --version
+THEUS_NO_OPEN_DASHBOARD=1 ./bin/theus
+curl http://127.0.0.1:<puerto>/api/status
+curl http://127.0.0.1:<puerto>/api/database
+```
+
+El typecheck global todavia arrastra deuda de tipos heredados y stubs reconstruidos. No se debe presentar como verde hasta cerrar esos tipos; los cambios deben validarse con pruebas enfocadas, smoke tests del CLI y verificaciones del dashboard.
+
+## Principios de producto
+
+- Local-first por defecto.
+- Cada usuario controla su modelo y su llave.
+- Cero marca externa en el copy visible.
+- Identidad Theus coherente: `theus`, `.theus`, `THEUS_*`, `theus.pe`.
+- El dashboard debe explicar el proyecto, no solo dibujar puntos.
+- Las bases de datos se muestran como capa visual real, con tablas, columnas, relaciones y fuente.
+- Las funciones incompletas se nombran como deuda tecnica, no como promesa terminada.
+
+## Marca
+
+Nombre: **Theus**  
+Dominio: **theus.pe**  
+Linea: **THEUS HECHO EN PERU**  
+Lema: **AD ASTRA PER ASPERA**  
+Color base: rojo Peru, blanco, grafito profundo, acentos dorado/verde para grafos y datos.
+
+Ultima actualizacion: 2026-07-06

package/bin/theus

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Theus launcher — type `theus` to start from any project.
+# Runs the project's Bun entrypoint with the build shims preloaded.
+# Any arguments are passed through, e.g.  theus --help   or   theus -p "hola".
+set -euo pipefail
+
+SOURCE="${BASH_SOURCE[0]}"
+while [[ -L "$SOURCE" ]]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+PROJ="$(cd -P "$(dirname "$SOURCE")/.." && pwd)"
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "theus: Bun no está instalado. Instálalo con: curl -fsSL https://bun.sh/install | bash" >&2
+  exit 1
+fi
+
+if [[ ! -f "$PROJ/entrypoints/cli.tsx" || ! -f "$PROJ/bun-shims/preload.ts" ]]; then
+  echo "theus: no encuentro el runtime en $PROJ" >&2
+  exit 1
+fi
+
+if [[ "${1:-}" == "login" || "${1:-}" == "signin" || "${1:-}" == "entrar" ]]; then
+  shift
+  exec bun --preload "$PROJ/bun-shims/preload.ts" "$PROJ/entrypoints/theus-login.ts" "$@"
+fi
+
+exec bun --preload "$PROJ/bun-shims/preload.ts" "$PROJ/entrypoints/cli.tsx" "$@"