@nac3/forge-cli 1.8.5 → 1.9.0

package/docs/doctrine/operate-mode.md

@@ -0,0 +1,118 @@
+# Operate-mode doctrine (Forge Embedded que CONFIGURA el sistema)
+
+El asistente residente nacio DIAGNOSTICO (ver `diagnostic-mode`): leer,
+consultar la base read-only, escribir reportes, y emitir la instruccion precisa
+para el operador. El **operate mode** (Pablo, 2026-10-10) es la salida ACOTADA
+de ese read-only: el asistente ademas CONFIGURA el sistema que atiende.
+
+## 1. El alcance, textual
+
+Tres cosas, y nada mas:
+
+1. **Configurar por ARCHIVOS de datos de configuracion** -- json, xml, txt,
+   ini, env, properties, yaml, toml, vaults.
+2. **Configurar por TABLAS de configuracion** -- UPDATE/INSERT estructurado
+   sobre tablas declaradas como configuracion.
+3. **Crear procesos nuevos y cronearlos en el orquestador** del sistema.
+
+Explicitamente AFUERA:
+
+4. **Las tablas de DATOS del sistema** no se tocan.
+5. **El software del sistema** no se modifica (codigo fuente, binarios, units,
+   definiciones de build o dependencias).
+
+## 2. Como se hace cumplir (no es prompt, es dispatcher)
+
+La ley de esta casa: *las reglas son enforcement, no prompt* -- un cerebro
+ignora un prompt. El alcance vive en `src/core/operate_guard.ts` y se aplica en
+tres capas, donde una capa posterior NUNCA puede ensanchar a la anterior:
+
+- **A. Invariantes compilados.** Toda extension que es software se rechaza
+  aunque el allowlist diga `**/*`; igual el arbol del SO (`/etc`, `/usr`,
+  `/boot`...), los esquemas de sistema de la base, y `.forge/` (el perfil que
+  otorga estos poderes: el asistente no puede ampliarse a si mismo).
+- **B. Allowlist del operador.** `operate.config_files.allow` (globs) y
+  `operate.config_tables.allow` (tablas) en `.forge/profile.<env>.json`.
+  **Default deny**: sin allowlist no se escribe nada. Las tablas de datos
+  quedan afuera por omision -- no hay que enumerarlas.
+- **C. Validacion por llamada.** Topes de tamano, columnas inmutables, WHERE
+  obligatorio, preflight de filas afectadas (0 filas -> no-op rechazado; mas
+  que `max_rows` -> cambio demasiado amplio rechazado), gramatica de cron,
+  saneado de nombres y argumentos que llegan a una linea de comando.
+
+Y una decision de diseno que sostiene el punto 4: **no existe ningun verbo que
+ejecute SQL mutante arbitrario**. El asistente pasa `{table, op, set, where}` y
+el servidor compone la sentencia con identificadores validados y valores
+literales. No hay superficie para "UPDATE pacientes SET ...".
+
+## 3. Los verbos
+
+| Verbo | Para que |
+| --- | --- |
+| `yujin.config.file-set` | Cambiar UN valor en un archivo de configuracion. Preferido: deja el resto del archivo byte a byte, hace backup y VERIFICA releyendo (si no verifica, restaura el backup y falla). |
+| `yujin.config.file-write` | Contenido completo, para lo que el editor puntual no puede expresar (XML complejo, blob de vault, archivo nuevo con `create:true`). Leer el archivo ANTES. |
+| `yujin.config.file-revert` | Restaurar un backup por `backup_id`. El contenido actual tambien se respalda: el revert es reversible. |
+| `yujin.config.table-set` | `{table, op: update\|insert\|delete, set, where}` sobre una tabla de configuracion allowlisteada. |
+| `yujin.orchestrator.process-create` | Registrar un proceso nuevo en el orquestador (y opcionalmente cronearlo en la misma llamada). |
+| `yujin.orchestrator.schedule-set` | Poner/cambiar el cron (5 campos Linux; `@daily` se rechaza) y el enabled de un proceso. |
+
+Los verbos solo aparecen en el manifest cuando el perfil habilita operate mode,
+y `nac3_invoke` los rechaza a nivel perfil cuando esta apagado. Un embed
+diagnostico comun es identico al build anterior.
+
+## 4. El orquestador se declara, no se adivina
+
+Cada sistema tiene su orquestador, asi que la FORMA la declara el operador una
+vez en `operate.orchestrator` y el cerebro solo aporta la intencion
+(`{name, command, cron}`). Tres adaptadores:
+
+- `db_table`: filas en las tablas del orquestador (`process_table` +
+  `schedule_table`) con un mapa logico -> columna real. El orquestador RPA
+  clasico.
+- `http`: POST a la API del propio orquestador (`base_url` + paths, key por env
+  var). **Preferido cuando el sistema valida y recarga sus agendas solo**: un
+  INSERT directo en un motor que hidrata su catalogo en memoria al arrancar no
+  tomaria efecto hasta un reinicio.
+- `cron_file`: fragmento de crontab en un directorio declarado, armado desde un
+  `command_template`. Para sistemas cuyo "orquestador" es cron.
+
+La URL / tabla / template siempre vienen del perfil: el asistente elige QUE
+agendar, nunca ADONDE postear ni QUE binario correr.
+
+## 5. Como trabajar un pedido de configuracion (siendo el asistente)
+
+1. **Triage**: contra el system map, confirmar que el pedido se resuelve
+   OPERANDO el sistema. Si es bug o excepcion no contemplada -> ticket.
+2. **Leer el valor actual** (`yujin.fs.read-file` / `yujin.db.query`). Nunca
+   escribir a ciegas: un archivo de config reconstruido de memoria pierde
+   settings en silencio.
+3. **Decir en una linea** que se va a cambiar y donde, antes de hacerlo.
+4. **Aplicar** con el verbo puntual, de a un valor.
+5. **Verificar** releyendo, y reportar `antes -> despues`.
+6. **Decir que falta para que tome efecto** (reload / restart / proximo tick).
+   Reiniciar un servicio NO es del asistente: se le da al operador el comando
+   exacto.
+7. **Todo queda en el journal** (`.forge/changes/changes.jsonl`) con backup del
+   archivo o before-image de la fila + sentencia de rollback. Ante la duda:
+   revertir, o pasarle al operador el rollback.
+8. Fuera del alcance sigue siendo el asistente DIAGNOSTICO: instruccion
+   precisa, pending, o ticket.
+
+`require_approval` (default true) muestra el cambio en el modal del panel antes
+de aplicarlo -- el operador ve exactamente que se va a tocar. Ponerlo en false
+es una decision deliberada del despliegue (queda igual en el journal).
+
+## 6. Como habilitarlo en un despliegue
+
+`yf embed` genera `.forge/profile.ops.json` (read_only + operate con allowlists
+VACIOS) y su unit `forge-<app>-ops.service` con `YF_ENV=ops`. Receta:
+
+1. Levantar el servicio ops con los allowlists vacios: el asistente ya
+   diagnostica y, como no hay nada declarado, no puede cambiar nada.
+2. Pedirle que construya/actualice su `system-map.md` y que **proponga** el
+   bloque `operate` -- que archivos de config y que tablas de configuracion
+   encontro, y como se registran y agendan los procesos.
+3. Revisar esa propuesta, recortarla (en la duda, afuera) y commitearla. El
+   asistente no puede ampliarse: `.forge/` esta fuera de su alcance.
+4. Reiniciar el servicio ops y probar UN cambio real de punta a punta
+   (antes -> despues -> journal -> revert).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nac3/forge-cli",
-  "version": "1.8.5",
+  "version": "1.9.0",
   "description": "Yujin Forge -- voice-first NAC-3 React development framework. CLI + chat panel + spec ingest + 10-format document reader + voice loop.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Pablo Kuschnirof <pablo@rpaforce.com>",