@ingeniomaps/cauce 0.31.0 → 0.33.0

package/CHANGELOG.md

@@ -14,6 +14,43 @@ desde este repositorio no va, porque el que lee no puede actuar sobre eso. Cuand
 unas pocas líneas casi siempre es porque cuenta cómo se descubrió el problema o por qué se eligió el
 diseño — eso vive en el commit y en el código.
 
+## [0.33.0] - 2026-08-19
+
+### Corregido
+
+- **Con varias raíces declaradas, ningún servicio tenía nombre.** Cada repositorio es la raíz de su
+  propio escaneo, así que su proyecto principal volvía como `.`: tres servicios llamados igual y nada que
+  los distinga. Una credencial no se podía atribuir a un servicio porque ningún servicio era nombrable, y
+  una corrida real terminó pidiéndole a una persona que declarara variables que su propio repositorio ya
+  declaraba. Ahora cada candidato lleva el nombre de su raíz, y donde hay una sola el proyecto de arriba
+  se nombra por su carpeta en vez de aparecer como `.` a secas.
+
+- **El arranque podía negar lo que el inventario le entregó.** Se le dice explícitamente que un nombre
+  que el inventario trae está declarado, así que pedir que se declare de nuevo contradice al repositorio.
+  La mitad de la corrección anterior que tocaba el recorrido —la que le hace copiar los nombres de
+  variable por servicio— no había llegado a publicarse.
+
+## [0.32.0] - 2026-08-19
+
+### Corregido
+
+- **Las credenciales de un multirepo no existían para el arranque.** `/onboard` leía un solo
+  `.env.example`, el de la raíz del workspace: en un monolito eso es todo, entre repositorios hermanos no
+  es nada. Una corrida real sobre tres repos dejó filas que decían «la credencial del proveedor» sin
+  nombrar una sola variable, y un externo que sólo ese archivo mencionaba —un certificado de organismo
+  fiscal— no apareció en ningún lado.
+
+  Ahora `ops scan` reporta, por servicio, los nombres que declara su ejemplo y de qué archivo salieron, y
+  el arranque los usa para nombrar cada fila. **Sólo los nombres**: el valor es de una persona, y el
+  ejemplo es la mitad pública del par. Se leen `.env.example`, `.env.sample`, `.env.template` y
+  `.env.dist`; un ejemplo de más de cuarenta variables es un archivo generado y no un contrato, así que
+  se corta ahí y lo dice.
+
+- **`ops scan <ruta>` dejaba afuera al proyecto de la raíz.** Un monolito que declara sus comandos en el
+  nivel de arriba volvía listando todo menos a sí mismo, mientras que desde adentro de la instancia el
+  mismo árbol sí lo listaba: dos respuestas distintas sobre el mismo directorio. Los dos caminos comparten
+  una sola función y el proyecto de la raíz va primero.
+
 ## [0.31.0] - 2026-08-18
 
 ### Añadido

package/automatization/workflows/onboard.js

@@ -85,6 +85,10 @@ const SCAN = {
           required: ['kind', 'command', 'source'], properties: {
             kind: { type: 'string' }, command: { type: 'string' }, source: { type: 'string' },
           } } },
+        // Los nombres de variable que ese servicio espera, copiados del inventario. En un multirepo cada
+        // repositorio trae su propio ejemplo, y sin esto las credenciales de tres repos no existían para
+        // el arranque: las filas terminaban diciendo «la credencial del proveedor» sin nombrarla.
+        env: { type: 'array', items: { type: 'string' } },
       } } },
     externals: { type: 'array', items: { type: 'string' } },
     secrets: { type: 'array', items: { type: 'string' } },
@@ -110,11 +114,12 @@ const state = await agent(
   `else and open no file other than .env.example at the workspace root.\n` +
   `1. "node tools/ops.js onboard --json": the instance state, the workspace inventory, the opening ` +
   `question and the dimensions still uncovered. Copy fresh, opening, followUps, the "need" of each ` +
-  `dimension, and every service with its path, its runtimes and its declared commands keeping the source ` +
-  `file each command came from. Add nothing it did not print.\n` +
+  `dimension, and every service with its path, its runtimes, its declared commands keeping the source ` +
+  `file each command came from, and the variable names its "env" carries. Add nothing it did not print.\n` +
   `2. "node tools/ops.js check planning".\n` +
-  `If .env.example exists at the workspace root, report the variable names in secrets —names only— and ` +
-  `the external services they point at in externals.`,
+  `The inventory already names every credential each service expects: never open a .env file to look for ` +
+  `more. Report those names in secrets and the services they point at in externals. A name the inventory ` +
+  `carries is declared, and saying otherwise is a claim the repository contradicts.`,
   { schema: SCAN, label: 'inventario' },
 )
 if (!state) return stop('scan-unavailable', 'no se pudo leer el estado del workspace')
@@ -167,8 +172,10 @@ const drafted = await agent(
     'completa.\n'}` +
   `4. ${HUMAN}: una fila por cada cosa que necesita a una persona, con la tarea, el estado pendiente, el ` +
   `origen "onboard" y la acción concreta que la desbloquea. Como mínimo, una por cada credencial que el ` +
-  `proyecto espera —dónde se cargan y quién lo hace, sin proponer ningún valor—, una por cada sistema ` +
-  `externo o MCP a conectar, y una por la autoridad del runner, que hoy declara runner.allowPush=false.\n` +
+  `inventario nombra, diciendo la variable y el servicio que la espera. El nombre ya está declarado, así ` +
+  `que no pidas declararlo de nuevo: lo que falta es dónde se carga el valor y quién lo hace, y ningún ` +
+  `valor se propone acá. Además, una por cada sistema externo o MCP a conectar, y una por la autoridad ` +
+  `del runner, que hoy declara runner.allowPush=false.\n` +
   `5. Las preguntas que queden abiertas, en la sección Ideas de ${INBOX}, sin promover.\n` +
   `Devolvé en files cada archivo que tocaste y en assumptions cada supuesto que dejaste marcado.`,
   { schema: WRITTEN, label: 'contexto' },

package/engine/cli/ops.js

@@ -353,29 +353,41 @@ function workspaceRoots(root) {
 
 // Qué hay en las raíces declaradas, antes de que nadie razone sobre ello. La raíz ops se saltea: no es
 // un servicio del proyecto, y su `package.json` sólo declara el motor.
+// Los candidatos de una raíz, con el proyecto que vive en ella misma primero: un monolito declara sus
+// comandos en el nivel de arriba, y dejarlo afuera hacía desaparecer justo al proyecto principal.
+function candidates(workspace, skip = '') {
+  const result = SC.scan(workspace, skip)
+  const found = result.rootManifests.length
+    ? [{ path: '.', root: workspace, runtimes: ['raíz'], commands: result.rootCommands, env: result.rootEnv }]
+    : []
+  return [...found, ...result.services.map((service) => ({ ...service, root: workspace }))]
+}
+
+// Con varias raíces, cada repositorio es la raíz de su propio escaneo y su candidato principal se llama
+// `.`: tres servicios con el mismo nombre y nada que los distinga. El prefijo los vuelve nombrables, que
+// es la única forma de que una credencial pueda atribuirse a un servicio en vez de quedar suelta.
 function inventory(root) {
-  const found = []
-  for (const workspace of workspaceRoots(root)) {
-    const result = SC.scan(workspace, root)
-    if (result.rootManifests.length) {
-      found.push({ path: '.', root: workspace, runtimes: ['raíz'], commands: result.rootCommands })
-    }
-    for (const service of result.services) found.push({ ...service, root: workspace })
-  }
-  return found
+  const roots = workspaceRoots(root)
+  if (roots.length === 1) return candidates(roots[0], root)
+  return roots.flatMap((workspace) => candidates(workspace, root).map((service) => ({
+    ...service,
+    path: service.path === '.' ? path.basename(workspace) : `${path.basename(workspace)}/${service.path}`,
+  })))
 }
 
 function scan(target, cli) {
   const root = path.resolve(target || '.')
-  const result = target
-    ? { root: path.resolve(target), services: SC.scan(path.resolve(target)).services }
-    : { root, services: inventory(root) }
+  const result = { root, services: target ? candidates(root) : inventory(root) }
   if (cli.has('--json')) return console.log(JSON.stringify(result, null, 2))
   // Un monorepo de sesenta paquetes no se lee en pantalla. Se recorta, y se dice cuánto: un corte que no
   // se anuncia hace pasar lo listado por todo lo que hay.
   for (const service of result.services.slice(0, LISTA)) {
-    const donde = service.root && service.root !== result.root ? `${path.basename(service.root)}/` : ''
-    console.log(`${donde}${service.path} [${(service.runtimes || []).join(', ')}]${comandos(service.commands)}`)
+    // El proyecto que vive en la raíz se nombra por su carpeta: `.` a secas no dice de cuál se habla.
+    const nombre = service.path === '.' ? `. (${path.basename(service.root || result.root)})` : service.path
+    const espera = service.env ? `\n    espera ${service.env.names.join(', ')} (${service.env.file})` : ''
+    console.log(
+      `${nombre} [${(service.runtimes || []).join(', ')}]${comandos(service.commands)}${espera}`,
+    )
   }
   if (result.services.length > LISTA) {
     console.log(`… y ${result.services.length - LISTA} más, todos en --json`)

package/engine/core/scan.js

@@ -98,6 +98,35 @@ function manifestsOf(dir) {
   return MANIFESTS.filter((entry) => fs.existsSync(path.join(dir, entry.file)))
 }
 
+// Qué credenciales espera un servicio, por su nombre y nada más. El ejemplo es público y versionado —el
+// `.env` de verdad no se toca nunca—, y los nombres son justo lo que hace falta para dejar una fila que
+// diga qué cargar; el valor no le corresponde a nadie más que a una persona.
+//
+// Se lee por servicio y no sólo en la raíz porque en un multirepo cada repositorio trae el suyo: leyendo
+// una sola raíz, las credenciales de tres repos se volvían invisibles y las acciones humanas terminaban
+// diciendo «la credencial del proveedor» en vez de nombrarla.
+const ENV_EXAMPLES = ['.env.example', '.env.sample', '.env.template', '.env.dist']
+
+// Un ejemplo con cientos de variables es un archivo generado, no un contrato: se corta y se dice.
+const ENV_MAX = 40
+
+function expectedEnv(dir) {
+  for (const name of ENV_EXAMPLES) {
+    const file = path.join(dir, name)
+    if (!fs.existsSync(file)) continue
+    let text = ''
+    try { text = fs.readFileSync(file, 'utf8') } catch { return null }
+    const names = text.split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith('#'))
+      .map((line) => line.replace(/^export\s+/, '').split('=')[0].trim())
+      .filter((key) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+    if (!names.length) return null
+    return { file: name, names: names.slice(0, ENV_MAX), truncated: Math.max(0, names.length - ENV_MAX) }
+  }
+  return null
+}
+
 // Servicios candidatos bajo `root`, sin entrar en `skip` —típicamente la raíz ops, que no es un
 // servicio del proyecto—. El resultado es una lista, no un veredicto: decidir cuál es el producto y
 // cuál quedó muerto sigue siendo trabajo de una persona o de un cargo.
@@ -113,6 +142,7 @@ function services(root, skip = '') {
         runtimes: manifests.map((entry) => entry.runtime),
         manifests: manifests.map((entry) => entry.file),
         commands: commandsOf(dir),
+        env: expectedEnv(dir),
       })
     }
     if (depth >= DEPTH) return
@@ -136,8 +166,9 @@ function scan(root, skip = '') {
     root: path.resolve(root),
     rootManifests: manifestsOf(root).map((entry) => entry.file),
     rootCommands: commandsOf(root),
+    rootEnv: expectedEnv(root),
     services: services(root, skip),
   }
 }
 
-module.exports = { scan, services, IGNORED, DEPTH }
+module.exports = { scan, services, expectedEnv, IGNORED, DEPTH, ENV_MAX }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingeniomaps/cauce",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "Sistema portable de planificación y ejecución verificable para cualquier proyecto",
   "keywords": [
     "planning",