theus-cli 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +112 -188
  2. package/cli.js +2739 -2605
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,103 +1,60 @@
1
- # THEUS
1
+ # THEUS — CLI
2
2
 
3
- **THEUS HECHO EN PERU**
4
- **AD ASTRA PER ASPERA**
5
- Dominio comercial: `theus.pe`
3
+ > **THEUS HECHO EN PERÚ · AD ASTRA PER ASPERA**
4
+ > Dominio: [`theus.pe`](https://theus.pe) · Docs: [`docs.theus.pe`](https://docs.theus.pe)
6
5
 
7
- 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.
6
+ **Theus** es un agente de código **local-first y multimodelo**: abre una sesión interactiva desde cualquier proyecto, lo indexa en tu propia máquina, mantiene memoria y un grafo del código, levanta un dashboard visual, y ejecuta tareas de programación con el modelo que elijas.
8
7
 
9
- Esto ya no es un documento de estudio ni una propuesta de rebrand. Este repositorio es la base del producto Theus.
8
+ Este repo es el **producto principal**: el CLI `theus` (Bun + Ink/React en TSX). El lado servidor (web, gateway y consola) vive en [`MarketrixPE/theus-pe`](https://github.com/MarketrixPE/theus-pe).
10
9
 
11
- ## Que hace Theus
10
+ ---
12
11
 
13
- - Abre una sesion interactiva desde cualquier proyecto con `theus`.
14
- - Indexa el proyecto localmente para reducir contexto repetido y mejorar memoria.
15
- - Levanta una API local en `127.0.0.1` con estado, grafo y esquema de base de datos.
16
- - Abre un dashboard visual del proyecto con mapa neuronal, archivos, simbolos, entidades, base de datos y memoria.
17
- - Permite conectar modelos locales, endpoints OpenAI-compatible o proveedores BYOK.
18
- - Mantiene paquetes propios en `vendor/theus-packages/` para preparar exports SDK, tipos y stubs de producto.
19
- - Usa identidad Theus: `.theus`, variables `THEUS_*`, dominio `theus.pe` y copy en espanol primero.
12
+ ## 🧠 Cómo encaja en el negocio
20
13
 
21
- ## Instalacion para usuarios
14
+ Theus se puede usar de dos maneras, y las dos son ciudadanas de primera clase:
22
15
 
23
- Requisito de runtime: **Bun**. Theus se compila y se ejecuta con Bun (`cli.js` es
24
- un bundle con target `bun`, no corre bajo Node). El instalador oficial instala
25
- Bun por ti si falta (descargando el binario oficial y verificando su checksum
26
- SHA-256).
16
+ 1. **Local-first / BYOK** — apunta el CLI a cualquier endpoint OpenAI-compatible (Ollama, LM Studio, un gateway propio, tu propia key). Todo corre en tu máquina; ningún servicio remoto es obligatorio para arrancar.
17
+ 2. **Suscripción Theus (gateway gestionado)** — `theus login` conecta el CLI al gateway de `theus.pe`. Con **una sola API key de Theus** accedes a los **~20 mejores modelos** (Claude, GPT, Gemini, DeepSeek, Grok, Qwen, GLM…). **Theus** administra centralmente las keys de cada proveedor; tú solo usas tu suscripción — **no traes tus propias keys de proveedor**.
27
18
 
28
- ### Opcion A — instalador oficial (recomendada)
19
+ En el modo suscripción, el modelo por defecto es **`titan`**: el orquestador propio de Theus que analiza cada petición, decide si la resuelve con **un modelo** o la **descompone entre varios**, y **sintetiza** la respuesta final. (Toda la lógica de TITAN, el catálogo y la gestión de keys está documentada en el README de [`theus-pe`](https://github.com/MarketrixPE/theus-pe).)
29
20
 
30
- ```bash
31
- curl -fsSL https://theus.pe/install.sh | bash
32
- theus --version
33
- ```
34
-
35
- El instalador detecta tu plataforma (macOS/Linux, x64/arm64), descarga el
36
- tarball del ultimo release de `MarketrixPE/theuscode` verificando su SHA-256,
37
- lo instala en `~/.theus/app` y enlaza el comando `theus` en tu PATH. Si aun no
38
- hay release publicado, cae automaticamente a instalar desde el codigo fuente
39
- (clona el repo y compila el bundle localmente).
21
+ > **Regla de producto:** el copy visible es **español-first** y **sin marcas externas**. La única excepción es el catálogo de modelos, donde sí aparecen los nombres reales.
40
22
 
41
- Variables opcionales del instalador:
23
+ ---
42
24
 
43
- | Variable | Efecto |
44
- | --- | --- |
45
- | `THEUS_INSTALL_MODE` | `auto` (def), `release` o `source` |
46
- | `THEUS_VERSION` | tag del release, p.ej. `v0.1.3` (def: `latest`) |
47
- | `THEUS_REF` / `THEUS_COMMIT` | rama y commit fijado para modo `source` |
48
- | `THEUS_HOME` | carpeta de instalacion (def: `~/.theus/app`) |
49
- | `THEUS_BIN_DIR` | donde enlazar `theus` (def: primer dir escribible del PATH) |
25
+ ## 🚀 Instalación (usuarios)
50
26
 
51
- Uso normal despues de instalar:
27
+ Requisito de runtime: **Bun** (`cli.js` es un bundle con target `bun`, no corre bajo Node). El instalador oficial instala Bun por ti si falta, verificando su checksum SHA-256.
52
28
 
53
29
  ```bash
54
- cd /ruta/de/tu/proyecto
55
- theus
30
+ curl -fsSL https://theus.pe/install.sh | bash
31
+ theus --version
56
32
  ```
57
33
 
58
- Para actualizar, vuelve a ejecutar el instalador (es idempotente).
59
-
60
- ### Opcion B — manual, desde un release
34
+ El instalador detecta tu plataforma (macOS/Linux, x64/arm64), descarga el tarball del último release (primario desde `theus.pe/dl`, con GitHub Releases como respaldo — el repo es privado), lo instala en `~/.theus/app` y enlaza `theus` en tu PATH. Es idempotente: para actualizar, vuelve a ejecutarlo.
61
35
 
62
- Descarga el tarball y el archivo de checksums desde
63
- `https://github.com/MarketrixPE/theuscode/releases`, verifica e instala:
36
+ **Alternativa vía npm** (también requiere Bun):
64
37
 
65
38
  ```bash
66
- curl -fsSLO https://github.com/MarketrixPE/theuscode/releases/latest/download/theus-cli.tar.gz
67
- curl -fsSLO https://github.com/MarketrixPE/theuscode/releases/latest/download/SHA256SUMS
68
- shasum -a 256 -c SHA256SUMS --ignore-missing # (en Linux: sha256sum -c)
69
- mkdir -p ~/.theus && tar -xzf theus-cli.tar.gz -C ~/.theus && mv ~/.theus/theus-cli ~/.theus/app
70
- ln -sf ~/.theus/app/bin/theus ~/.local/bin/theus
39
+ npm install -g theus-cli
71
40
  ```
72
41
 
73
- ### Opcion C — manual, desde el repositorio (desarrollo)
74
-
75
- ```bash
76
- git clone https://github.com/MarketrixPE/theuscode.git
77
- cd theuscode
78
- bun install
79
- bun run build # genera cli.js self-contained
80
- ./cli.js --version # o: bun run dev
81
- ```
42
+ Variables del instalador: `THEUS_INSTALL_MODE` (`auto`|`release`|`source`), `THEUS_VERSION` (`latest` o `vX.Y.Z`), `THEUS_HOME`, `THEUS_BIN_DIR`.
82
43
 
83
- Para escribir `theus` desde cualquier proyecto durante el desarrollo, enlaza el
84
- bundle compilado:
44
+ ### Primer uso
85
45
 
86
46
  ```bash
87
- ln -sf "$(pwd)/cli.js" /usr/local/bin/theus
47
+ cd /ruta/de/tu/proyecto
48
+ theus # sesión interactiva
49
+ theus -p "tu prompt" # modo no interactivo
50
+ theus login # conectar la suscripción Theus
88
51
  ```
89
52
 
90
- > Nota: la publicacion en npm (`npm install -g theus-cli`) esta preparada en
91
- > `package.json` pero el paquete aun no esta publicado en el registry. Los
92
- > releases se generan con `bun run release` (`scripts/release.ts`) y el
93
- > workflow `.github/workflows/release.yml` los publica al pushear un tag
94
- > `vX.Y.Z`.
95
-
96
- ## Conectar un modelo
53
+ ---
97
54
 
98
- Theus lee primero variables `THEUS_*`. Puedes apuntar a Ollama, LM Studio, LiteLLM, OpenRouter, un gateway propio o cualquier servidor OpenAI-compatible.
55
+ ## 🧩 Conectar un modelo
99
56
 
100
- Ejemplo con endpoint local:
57
+ Theus lee primero las variables `THEUS_*`. Apunta a cualquier endpoint OpenAI-compatible:
101
58
 
102
59
  ```bash
103
60
  export THEUS_BASE_URL="http://127.0.0.1:11434/v1"
@@ -106,162 +63,129 @@ export THEUS_API_KEY="local"
106
63
  theus
107
64
  ```
108
65
 
109
- Ejemplo con archivo de proveedores:
66
+ O define proveedores en `~/.theus/providers.json`:
110
67
 
111
68
  ```json
112
69
  {
113
70
  "providers": [
114
- {
115
- "id": "ollama",
116
- "adapter": "openai-compatible",
117
- "enabled": true,
118
- "options": {
119
- "baseURL": "http://127.0.0.1:11434/v1",
120
- "model": "llama3.1",
121
- "apiKey": "local"
122
- }
123
- }
71
+ { "id": "ollama", "adapter": "openai-compatible", "enabled": true,
72
+ "options": { "baseURL": "http://127.0.0.1:11434/v1", "model": "llama3.1", "apiKey": "local" } }
124
73
  ],
125
- "policy": {
126
- "text": ["ollama"]
127
- }
74
+ "policy": { "text": ["ollama"] }
128
75
  }
129
76
  ```
130
77
 
131
- Ruta esperada del archivo:
78
+ **`theus login`** hace el flujo OAuth/PKCE contra `theus.pe`, intercambia el código por token y deja instalado el proveedor `theus-official` (`https://theus.pe/v1`, modelo `titan`) en `~/.theus/providers.json`. A partir de ahí basta con `theus`.
132
79
 
133
- ```text
134
- ~/.theus/providers.json
135
- ```
80
+ **Orden de selección de proveedor** (`services/api/theus.ts`): `THEUS_DISABLE_MAIN_PROVIDER=1` → env `THEUS_BASE_URL`/`THEUS_OPENAI_BASE_URL` → primer proveedor con texto en `providers.json` → motor de compatibilidad. Ningún servicio remoto es obligatorio para arrancar.
81
+
82
+ ### Variables útiles
136
83
 
137
- ## Dashboard local
84
+ | Variable | Uso |
85
+ | --- | --- |
86
+ | `THEUS_BASE_URL` / `THEUS_OPENAI_BASE_URL` | endpoint OpenAI-compatible |
87
+ | `THEUS_MODEL` / `THEUS_API_KEY` / `THEUS_PROVIDER_ID` | modelo, key y nombre del proveedor |
88
+ | `THEUS_DISABLE_MAIN_PROVIDER=1` | fuerza el motor de compatibilidad |
89
+ | `THEUS_NO_PROJECT_INTELLIGENCE=1` | no levanta índice/API/dashboard |
90
+ | `THEUS_NO_OPEN_DASHBOARD=1` | levanta la API sin abrir el navegador |
91
+ | `PROJECT_API_PORT` / `INDEX_MAX_FILES` | puerto local / límite de archivos indexados |
138
92
 
139
- Al iniciar Theus dentro de un proyecto, el servicio de inteligencia local:
93
+ ---
140
94
 
141
- - recorre archivos relevantes,
142
- - extrae simbolos,
143
- - construye nodos y relaciones,
144
- - detecta esquemas SQL/Prisma,
145
- - guarda indice y memoria bajo `~/.theus/knowledge/`,
146
- - expone un dashboard local.
95
+ ## 📊 Dashboard e inteligencia local
147
96
 
148
- Endpoints disponibles:
97
+ Al iniciar dentro de un proyecto, el servicio de inteligencia local indexa archivos, extrae símbolos, construye el grafo, detecta esquemas SQL/Prisma, guarda índice y memoria en `~/.theus/knowledge/` y expone un dashboard en `127.0.0.1`:
149
98
 
150
99
  ```text
151
- /dashboard
152
- /api/health
153
- /api/status
154
- /api/graph
155
- /api/database
156
- /api/db
157
- /api/schema
100
+ /dashboard /api/status /api/graph /api/database /api/schema /api/health
158
101
  ```
159
102
 
160
- ## Login y cuenta Theus
103
+ ---
161
104
 
162
- El flujo remoto usa la arquitectura OAuth heredada, pero servida por `theus.pe`.
105
+ ## 🛠️ Desarrollo
163
106
 
164
- ```text
165
- GET https://theus.pe/cai/oauth/authorize
166
- POST https://theus.pe/v1/oauth/token
167
- GET https://theus.pe/api/oauth/profile
168
- GET https://theus.pe/api/oauth/theus_cli/roles
169
- POST https://theus.pe/api/oauth/theus_cli/create_api_key
107
+ ```bash
108
+ bun install
109
+ bun run dev # corre desde fuente (entrypoints/cli.tsx)
110
+ ./bin/theus --version # vía el launcher (preload de shims)
111
+ bun run build # bundle → ./cli.js (usa el macro feature(); --define feature=false)
112
+ bun run typecheck # tsc --noEmit — ⚠️ ver caveat
170
113
  ```
171
114
 
172
- Uso directo:
115
+ **Smoke tests** (la verificación real, no el typecheck):
173
116
 
174
117
  ```bash
175
- theus login
118
+ THEUS_NO_PROJECT_INTELLIGENCE=1 ./bin/theus --help
119
+ THEUS_NO_OPEN_DASHBOARD=1 ./bin/theus
120
+ curl http://127.0.0.1:<puerto>/api/status
121
+ curl http://127.0.0.1:<puerto>/api/database
176
122
  ```
177
123
 
178
- 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.
179
-
180
- Al completarse, `theus login` instala tambien el proveedor oficial
181
- `theus-official` en `~/.theus/providers.json` con base
182
- `https://theus.pe/v1` y modelo `theus-router-auto`. Asi el usuario puede
183
- entrar con `theus` y enviar prompts sin exportar variables manuales.
124
+ > **Caveat de typecheck:** `bun run typecheck` aún falla por deuda de tipos heredada y stubs reconstruidos. **No** lo trates como gate. Valida con tests enfocados + smoke tests del CLI + chequeos del dashboard.
184
125
 
185
- Variables utiles:
126
+ ### Flujo de arranque
186
127
 
187
- | Variable | Uso |
188
- | --- | --- |
189
- | `THEUS_BASE_URL` | URL base del proveedor OpenAI-compatible |
190
- | `THEUS_OPENAI_BASE_URL` | Alias compatible para proveedor OpenAI-compatible |
191
- | `THEUS_MODEL` | Modelo principal |
192
- | `THEUS_OPENAI_MODEL` | Alias compatible de modelo |
193
- | `THEUS_API_KEY` | API key del proveedor |
194
- | `THEUS_PROVIDER_ID` | Nombre visible del proveedor activo |
195
- | `THEUS_DISABLE_MAIN_PROVIDER=1` | Fuerza el motor de compatibilidad |
196
- | `THEUS_DISABLE_TOOLS=1` | Desactiva tool-calling para endpoints simples |
197
- | `THEUS_NO_PROJECT_INTELLIGENCE=1` | No levanta indice/API/dashboard |
198
- | `THEUS_NO_OPEN_DASHBOARD=1` | Levanta API sin abrir el navegador |
199
- | `THEUS_START_MENU=1` | Muestra el menu visual de arranque antes del prompt |
200
- | `THEUS_NO_START_MENU=1` | Fuerza saltar el menu visual incluso si se pidio |
201
- | `PROJECT_API_PORT=65235` | Fija el puerto local |
202
- | `INDEX_MAX_FILES=2500` | Limite de archivos indexados |
203
- | `THEUS_ENABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1` | Opt-in para marketplace oficial |
204
-
205
- ## Comandos principales
206
-
207
- | Comando | Proposito |
208
- | --- | --- |
209
- | `theus` | Inicia la sesion interactiva |
210
- | `theus -p "prompt"` | Ejecuta en modo no interactivo |
211
- | `theus --help` | Muestra ayuda |
212
- | `/help` | Ayuda dentro del REPL |
213
- | `/login` | Configuracion de acceso cuando se usa una cuenta remota |
214
- | `/model` | Seleccion de modelo |
215
- | `/mcp` | Servidores MCP |
216
- | `/permissions` | Permisos de herramientas |
217
- | `/init` | Inicializa documentacion de proyecto |
128
+ ```
129
+ bin/theus → entrypoints/cli.tsx → main.tsx → setup.ts → replLauncher.tsx → screens/REPL.tsx → query.ts
130
+ ```
218
131
 
219
- 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`.
132
+ `bin/theus` corre Bun con `--preload bun-shims/preload.ts` (registra el shim del macro `feature()`/`bun:bundle` y stubs internos para correr sin bundlear). `login`/`signin`/`entrar` los intercepta el launcher y los enruta a `entrypoints/theus-login.ts`.
220
133
 
221
- ## Estructura importante
134
+ ### Mapa de arquitectura
222
135
 
223
136
  ```text
224
- bin/theus launcher local
225
- entrypoints/cli.tsx entrada del CLI
226
- main.tsx entrada UI heredada, evitar editar en bloque
227
- screens/REPL.tsx REPL interactivo
228
- components/Theus/ banner, menu, setup de proveedor
229
- services/api/theus.ts router OpenAI-compatible y fallback
230
- services/projectIntelligence/ API local, dashboard, base de datos visual
231
- services/knowledge/ indice, memoria y grafo local
232
- vendor/theus-packages/ paquetes propios SDK/MCP
233
- types/theus-sdk.d.ts tipos publicos base
137
+ services/api/theus.ts proveedor de modelos — router OpenAI-compatible + fallback
138
+ services/knowledge/ índice local, grafo del proyecto, memoria (~/.theus/knowledge/)
139
+ services/projectIntelligence/ API HTTP local + dashboard + DB visual (detección SQL/Prisma)
140
+ tools.ts registro de herramientas (¡el orden importa!)
141
+ commands.ts registro de slash-commands (¡el orden importa!)
142
+ components/Theus/ banner (Prometeo ASCII), menú, setup de proveedor
143
+ vendor/theus-packages/ paquetes propios (agent-sdk, sdk, mcpb)
144
+ vendor/theus-stubs/ stubs reconstruidos de deps privadas/3ras
145
+ types/ tipos públicos + shims
234
146
  ```
235
147
 
236
- ## Calidad y verificacion
148
+ ---
149
+
150
+ ## ⚠️ Convenciones que NO se rompen (léelas antes de tocar código)
151
+
152
+ Este CLI es una reconstrucción de un agente upstream: varios invariantes de build son **load-bearing** y fáciles de romper sin querer.
237
153
 
238
- Smoke tests recomendados:
154
+ - **Mantén las extensiones `.js` en imports ESM** aunque el archivo fuente sea `.ts`/`.tsx`.
155
+ - Usa `import type` para imports de solo-tipo (`verbatimModuleSyntax` está activo).
156
+ - **No auto-ordenes ni reordenes `tools.ts` ni `commands.ts`** — el orden es significativo.
157
+ - `feature("FLAG")` es un **macro de build**, no un `if` de runtime. No lo reescribas como condicional normal; el bundler hace dead-code-elimination desde ahí (`build` pasa `--define feature=false`). Los módulos gateados por build se cargan con `require()` condicional dentro de un ternario.
158
+ - No renombres mecánicamente `process.env.USER_TYPE === 'ant'` — es un gate de build heredado.
159
+ - Evita editar `main.tsx` en bloque (entrada grande heredada). Prefiere `components/`, `hooks/`, `screens/`, `services/`, `tools/`, `commands/`.
160
+ - No cambies prompts sensibles sin motivo: `query.ts`, reglas de thinking, permisos, seguridad, prompts de herramientas.
161
+
162
+ ### Añadir una herramienta o comando
163
+
164
+ - **Herramienta:** `buildTool(...) satisfies ToolDef<...>`, constante de nombre en `prompt.ts`/`constants.ts`, regístrala en `getAllBaseTools()`, declara permisos + destructividad con precisión, y añádela a `constants/tools.ts` si los subagentes deben verla.
165
+ - **Slash-command:** vive en `commands/<nombre>/`, tipo `prompt` | `local` | `local-jsx`. Mantén `COMMANDS` como función memoizada — no la conviertas en array top-level.
166
+
167
+ ---
168
+
169
+ ## 🚢 Releases y distribución
239
170
 
240
171
  ```bash
241
- ./bin/theus --version
242
- THEUS_NO_OPEN_DASHBOARD=1 ./bin/theus
243
- curl http://127.0.0.1:<puerto>/api/status
244
- curl http://127.0.0.1:<puerto>/api/database
172
+ bun run scripts/release.ts --tag vX.Y.Z # genera dist/release/* + SHA256SUMS
245
173
  ```
246
174
 
247
- 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.
175
+ Luego: sube `dist/release/*` a `/var/www/theus.pe/dl/` (y `/dl/vX.Y.Z/`), crea el release en GitHub (`MarketrixPE/theuscode`), y publica en npm (`theus-cli`; requiere OTP salvo con token de automatización). El paquete npm es solo el bundle compilado (`cli.js` + bin + arte ASCII + README): **no expone la fuente privada**.
248
176
 
249
- ## Principios de producto
177
+ ---
250
178
 
251
- - Local-first por defecto.
252
- - Cada usuario controla su modelo y su llave.
253
- - Cero marca externa en el copy visible.
254
- - Identidad Theus coherente: `theus`, `.theus`, `THEUS_*`, `theus.pe`.
255
- - El dashboard debe explicar el proyecto, no solo dibujar puntos.
256
- - Las bases de datos se muestran como capa visual real, con tablas, columnas, relaciones y fuente.
257
- - Las funciones incompletas se nombran como deuda tecnica, no como promesa terminada.
179
+ ## 📖 Docs adicionales del subproyecto
258
180
 
259
- ## Marca
181
+ - `AGENTS.md` — reglas de trabajo para agentes.
182
+ - `THEUS.md` — manual de producto/operaciones.
183
+ - `THEUS_SOURCE_NOTES.md` — internals de runtime/build.
260
184
 
261
- Nombre: **Theus**
262
- Dominio: **theus.pe**
263
- Linea: **THEUS HECHO EN PERU**
264
- Lema: **AD ASTRA PER ASPERA**
265
- Color base: rojo Peru, blanco, grafito profundo, acentos dorado/verde para grafos y datos.
185
+ ## Principios de producto
266
186
 
267
- Ultima actualizacion: 2026-07-06
187
+ - Local-first por defecto; cada usuario controla su modelo y su llave.
188
+ - Cero marca externa en el copy visible (excepto el catálogo de modelos).
189
+ - Identidad Theus coherente: `theus`, `.theus`, `THEUS_*`, `theus.pe`.
190
+ - El dashboard **explica** el proyecto, no solo dibuja puntos.
191
+ - Las funciones incompletas se nombran como deuda técnica, no como promesa terminada.