@ingeniomaps/cauce 0.54.0 → 0.55.0

package/CHANGELOG.md

@@ -14,6 +14,49 @@ 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.55.0] - 2026-09-02
+
+### Corregido
+
+- **`upgrade` ya no pisa lo que `init --force` conservó.** Adoptar Cauce en un repositorio que ya tiene
+  contenido es `init --force` y después `upgrade`. El primero conserva tus archivos y lo cumple; el
+  segundo los reemplazaba sin avisar e imprimía que no había tocado nada propio. El registro se grababa
+  hasheando el disco, así que un archivo conservado quedaba anotado como entregado por Cauce con **tu**
+  contenido, y la comparación no veía ninguna diferencia. Ahora se anota el digest de lo que el molde
+  habría escrito: tu archivo se ve como lo que es —una edición local— y `upgrade` se detiene
+  nombrándolo. **Qué cambia para vos**: el primer `upgrade` después de una adopción con `--force` se
+  detiene listando esos archivos. Resolvelos a mano, o repetí con `--force` para descartarlos, que
+  ahora además los enumera en la salida.
+- **Tu guard propio sobrevive a `automation install`.** `AGENTS.md` te dice que lo pongas en
+  `automatization/hooks/guard-<nombre>.sh` y promete que sobrevive a cada actualización. Sobrevivía al
+  `upgrade` y no a la reinstalación del runner: lo nuestro se reconocía por la carpeta, así que
+  cualquier `guard-*.sh` de ahí se desregistraba antes de fusionar. El archivo quedaba en disco, el
+  guard dejaba de correr y lo único que se veía era una línea diciendo que se había quitado una entrada
+  obsoleta. Ahora se reconoce por lo que efectivamente entregamos: los guards que el motor trae, más
+  los que esta instancia anotó haber recibido —el manifiesto gana una entrada por runner con el wiring
+  que dejó puesto, y por eso una entrada nuestra se sigue retirando el día que el motor deje de traer
+  ese guard—. **Si moviste tu guard fuera de esa carpeta para sortearlo, ya podés devolverlo.**
+- **`automation doctor` deja de llamar divergente a una configuración completa.** Un hook propio sumado
+  *dentro* de un grupo que escribió el toolkit dejaba a `doctor` en rojo aunque estuvieran todas las
+  entradas esperadas: comparaba el grupo entero serializado, así que uno con un hook de más contaba
+  como ausente. Ahora compara por `matcher` y contenido. Lo que falta se sigue reportando igual.
+- **`upgrade --check` avisa de lo que tenés editado aunque la versión coincida.** Salía por un camino
+  corto que informaba «al día» sin llegar a listarlo, que es el estado normal entre actualizaciones
+  —`init` fija la versión exacta—: el único modo que no toca nada era también el único que no podía
+  anticipar el conflicto. **Qué cambia para vos**: `--check` ahora sale 1 cuando hay archivos del
+  sistema editados, un caso donde antes salía 0. Si lo tenés en un script, revisá esa condición.
+
+### Cambiado
+
+- **`init` e `init .` eligen el mismo modo en el mismo directorio.** El default salía de si escribiste
+  el argumento, no de a dónde apunta: en `acme-ops/`, `init` daba `sidecar` e `init .` daba `embedded`.
+  No es cosmético — en `embedded` la raíz del workspace pasa a ser la carpeta ops misma, así que
+  `guard-workspace-boundary` deja de reconocer los repos hermanos y el wiring del runner se escribe
+  adentro en vez de al lado, donde abrís tu herramienta. Ahora lo decide el destino resuelto, con la
+  misma regla que ya elegía dónde aterrizar: una carpeta llamada `ops` o terminada en `-ops` **es** la
+  instancia. **Qué cambia para vos**: `init .` en una carpeta así ahora da `sidecar`, donde antes daba
+  `embedded`. El caso embebido sigue disponible pidiéndolo: `init . --mode embedded`.
+
 ## [0.54.0] - 2026-09-02
 
 ### Agregado

package/engine/automation/config.js

@@ -8,7 +8,7 @@
 const fs = require('node:fs')
 const path = require('node:path')
 const F = require('../core/files')
-const { supersededGuards } = require('./hooks')
+const { supersededGuards, expectedHooks } = require('./hooks')
 
 function mergeConfig(current, incoming) {
   if (Array.isArray(incoming)) {
@@ -32,19 +32,40 @@ function mergeConfig(current, incoming) {
   return incoming
 }
 
-// Una entrada de hook que puso Cauce se reconoce por el guard al que apunta: `automatization/hooks/`
-// es nuestro y ninguna empresa escribe ahí. Se saca del archivo del usuario antes de fusionar para que
-// el merge deje exactamente las de esta versión, ni una más.
-const DELIVERED = /automatization\/hooks\/guard-[a-z-]+\.sh/
+// Una entrada de hook que puso Cauce se reconoce por el guard al que apunta, y lo nuestro es lo que
+// efectivamente entregamos, no todo lo que vive en nuestra carpeta. Reconocer por directorio
+// desregistraba el guard propio del proyecto en cada reinstalación: `template/AGENTS.md` invita a
+// ponerlo justo ahí y promete que sobrevive a cada actualización, el archivo quedaba en disco, y lo
+// único que se veía era una línea diciendo que se había quitado una entrada obsoleta.
+// Se saca del archivo del usuario antes de fusionar para que el merge deje exactamente las de esta
+// versión, ni una más.
+const HOOK_PATH = /automatization\/hooks\/([a-z0-9-]+\.sh)(?:\s|$)/
 
-function withoutDeliveredHooks(config, live) {
+// Dos fuentes, y la segunda es la que cierra el borde. `expectedHooks()` dice qué entrega el motor de
+// hoy y alcanza para una instancia que nunca instaló; `delivered` es lo que esta instancia registró
+// haber recibido la última vez, y es lo único que reconoce un guard que entregamos en una versión y
+// retiramos en la siguiente: su nombre ya no está en la lista de hoy, así que sin el registro quedaría
+// vivo en la configuración llamando a un guard que Cauce ya no mantiene. Un guard propio del proyecto
+// no está en ninguna de las dos, que es exactamente por lo que sobrevive.
+function isDelivered(command, delivered) {
+  const hit = String(command).match(HOOK_PATH)
+  if (!hit) return false
+  return expectedHooks().includes(hit[1]) || delivered.has(String(command))
+}
+
+// Lo que de un conjunto de comandos es wiring de guards nuestro, para anotarlo como entregado.
+function deliveredHookCommands(commands) {
+  return [...commands].filter((command) => HOOK_PATH.test(String(command)))
+}
+
+function withoutDeliveredHooks(config, live, delivered = new Set()) {
   const dropped = []
   const walk = (node) => {
     if (Array.isArray(node)) {
       return node
         .filter((item) => {
           const command = item && typeof item === 'object' ? String(item.command || '') : ''
-          if (!DELIVERED.test(command)) return true
+          if (!isDelivered(command, delivered)) return true
           // Sólo se anuncia lo que ya no vuelve: una entrada que el merge repone quedó igual, y decir
           // que se quitó y se puso la misma línea es ruido que esconde el caso que sí importa.
           if (!live.has(command)) dropped.push(command)
@@ -83,9 +104,20 @@ function reportRemoved(name, dropped, live, output) {
 
 function includesConfig(actual, expected) {
   if (Array.isArray(expected)) {
-    return Array.isArray(actual) && expected.every((item) => {
-      return actual.some((value) => JSON.stringify(value) === JSON.stringify(item))
-    })
+    return Array.isArray(actual) && expected.every((item) => actual.some((value) => {
+      // Un grupo de hooks se compara por su contenido, no por su forma serializada. La comprobación es
+      // «contiene», que es lo correcto, pero con el ítem entero como unidad un grupo `{matcher, hooks}`
+      // con un hook de más dejaba de ser el mismo objeto y contaba como ausente: `doctor` llamaba
+      // divergente a una configuración que tenía todo lo esperado, y el anidamiento —donde vive la
+      // diferencia real— no se miraba nunca. La instalación promete conservar lo que el proyecto ya
+      // tenía, así que sumar un hook propio a un grupo nuestro es exactamente lo que permite.
+      if (item && typeof item === 'object' && Array.isArray(item.hooks)) {
+        return value && typeof value === 'object'
+          && value.matcher === item.matcher
+          && includesConfig(value.hooks, item.hooks)
+      }
+      return JSON.stringify(value) === JSON.stringify(item)
+    }))
   }
   if (expected && typeof expected === 'object') {
     return actual && typeof actual === 'object' && Object.entries(expected).every(([key, value]) => {
@@ -170,6 +202,6 @@ function blockUpToDate(file, name, content) {
 
 module.exports = {
   blockStart,
-  mergeConfig, withoutDeliveredHooks, reportRemoved, includesConfig, hasHooks,
+  mergeConfig, withoutDeliveredHooks, deliveredHookCommands, reportRemoved, includesConfig, hasHooks,
   unmergeConfig, isSharedFile, withoutBlock, mergeInstruction, blockUpToDate,
 }

package/engine/automation/index.js

@@ -17,7 +17,7 @@ const {
   legacyGuardWiring, staleHooks, listHooks,
 } = require('./hooks')
 const {
-  blockStart, mergeConfig, withoutDeliveredHooks, reportRemoved, includesConfig, hasHooks,
+  blockStart, mergeConfig, withoutDeliveredHooks, deliveredHookCommands, reportRemoved, includesConfig, hasHooks,
   unmergeConfig, isSharedFile, withoutBlock, mergeInstruction, blockUpToDate,
 } = require('./config')
 
@@ -226,6 +226,11 @@ function deliveryKey(name, target) {
   return `${name}/${target.split(path.sep).join('/')}`
 }
 
+// La sección `runners` del manifiesto anota archivo → digest; ésta es la única entrada que guarda una
+// lista, porque lo que registra no es un archivo sino las entradas que dejamos dentro del archivo de
+// configuración del usuario. No colisiona con ningún `target`: ninguno se llama así.
+const HOOKS_KEY = 'config.hooks'
+
 // En qué estado quedó un archivo que este adaptador entregó alguna vez.
 //
 //   nuevo          no existe todavía
@@ -277,6 +282,7 @@ function uninstall(root, name, output = console) {
 
   const items = [...(runner.instructions || []), ...(runner.artifacts || [])]
   const deliveredPaths = { ...recorded }
+  delete deliveredPaths[deliveryKey(name, HOOKS_KEY)]
   for (const item of items) {
     const resolved = { item, ...resolveItem(paths, root, name, item) }
     const key = deliveryKey(name, item.target)
@@ -378,7 +384,12 @@ function install(root, name, output = console, options = {}) {
   // guard que el runner intenta ejecutar y falla. Se quitan las nuestras y las vuelve a poner el merge.
   const live = new Set((JSON.stringify(incoming).match(/"command":"[^"]*"/g) || [])
     .map((entry) => JSON.parse(`{${entry}}`).command))
-  const clean = runner.config.owned ? { config: {}, dropped: [] } : withoutDeliveredHooks(current, live)
+  // Lo que este adaptador anotó haber entregado la última vez. Es lo único que reconoce una entrada
+  // nuestra cuyo guard el motor ya no trae: por nombre no se distingue de la que agregó el proyecto.
+  const previous = new Set(recorded[deliveryKey(name, HOOKS_KEY)] || [])
+  const clean = runner.config.owned
+    ? { config: {}, dropped: [] }
+    : withoutDeliveredHooks(current, live, previous)
   reportRemoved(name, clean.dropped, live, output)
   F.atomicWriteJson(paths.configTarget, mergeConfig(clean.config, incoming))
   // Dónde aterrizó, no sólo qué archivo: en sidecar el destino no es el repo desde el que se corrió
@@ -388,6 +399,12 @@ function install(root, name, output = console, options = {}) {
   }
   output.log(`✓ ${name}: configuración instalada en ${runner.config.target}`)
   const deliveredPaths = { ...recorded }
+  // Qué wiring de guards dejamos puesto, para poder retirarlo el día que el motor deje de traerlo. Se
+  // anota lo que instalamos y no lo que quedó en el archivo: ahí conviven las entradas del proyecto, y
+  // registrarlas nos autorizaría a borrar lo ajeno en la instalación siguiente.
+  const ourHooks = deliveredHookCommands(live)
+  if (ourHooks.length) deliveredPaths[deliveryKey(name, HOOKS_KEY)] = ourHooks
+  else delete deliveredPaths[deliveryKey(name, HOOKS_KEY)]
   for (const resolved of resolvedItems) {
     const status = state.get(resolved)
     const ownFile = runner.instructions.includes(resolved.item)

package/engine/cli/instance.js

@@ -29,9 +29,14 @@ function providerNames() {
   } catch { return [] }
 }
 
+// Devuelve, por archivo conservado, el digest de lo que el molde **habría** escrito. Adoptar Cauce en
+// un repositorio con contenido es `init --force`, y lo que se conserva ahí lo escribió la empresa: si
+// el manifiesto lo registra hasheando el disco queda declarado como entregado por Cauce con contenido
+// que Cauce nunca entregó, y el `upgrade` siguiente no ve ninguna edición local y lo reemplaza.
 function copyTemplate(source, target, replacements, force, skip = [], quiet = false) {
   F.assertNoSymlinkPath(path.dirname(target), target)
   fs.mkdirSync(target, { recursive: true })
+  const preserved = {}
   for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
     if (skip.includes(entry.name)) continue
     const from = path.join(source, entry.name)
@@ -39,11 +44,14 @@ function copyTemplate(source, target, replacements, force, skip = [], quiet = fa
     // 11.16.0: lo deja afuera en la raíz y en subdirectorios—, así que viaja sin punto y se restituye
     // acá. Sin esto el archivo existe en el repo del toolkit y desaparece para todo consumidor real.
     const to = path.join(target, entry.name === 'gitignore' ? '.gitignore' : entry.name)
-    if (entry.isDirectory()) copyTemplate(from, to, replacements, force, skip, quiet)
+    if (entry.isDirectory()) Object.assign(preserved, copyTemplate(from, to, replacements, force, skip, quiet))
     else {
       if (fs.existsSync(to)) {
         if (!force) fail(`El destino contiene ${to}. Usa un directorio vacío o --force.`)
         if (!quiet) console.log(`= conservado ${to}`)
+        let would = fs.readFileSync(from, 'utf8')
+        for (const [key, value] of Object.entries(replacements)) would = would.replaceAll(key, value)
+        preserved[to] = M.digestText(would)
         continue
       }
       let content = fs.readFileSync(from, 'utf8')
@@ -53,22 +61,29 @@ function copyTemplate(source, target, replacements, force, skip = [], quiet = fa
       if (!quiet) console.log(`+ ${to}`)
     }
   }
+  return preserved
 }
 
+// Devuelve lo conservado igual que `copyTemplate`, y por la misma razón: acá el runtime no lleva
+// reemplazos, así que lo que habríamos escrito es el archivo del paquete tal cual.
 function copyRuntime(source, target, preserve = false, boundary = target, skip = []) {
   F.assertNoSymlinkPath(boundary, target)
   fs.mkdirSync(target, { recursive: true })
+  const preserved = {}
   for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
     if (skip.includes(entry.name)) continue
     const from = path.join(source, entry.name)
     const to = path.join(target, entry.name)
-    if (entry.isDirectory()) copyRuntime(from, to, preserve, boundary, skip)
-    else if (preserve && fs.existsSync(to)) console.log(`= conservado ${to}`)
-    else {
+    if (entry.isDirectory()) Object.assign(preserved, copyRuntime(from, to, preserve, boundary, skip))
+    else if (preserve && fs.existsSync(to)) {
+      console.log(`= conservado ${to}`)
+      preserved[to] = M.digest(from)
+    } else {
       F.assertNoSymlinkPath(boundary, to)
       fs.copyFileSync(from, to)
     }
   }
+  return preserved
 }
 
 // Declara el motor como dependencia exacta: el lockfile decide qué versión corre, no una copia.
@@ -116,7 +131,7 @@ function undeclareEngine(manifest) {
 // el banco de evaluación lo llama directo: crear una instancia programáticamente no puede depender de
 // cómo venga escrita la línea de comandos.
 function scaffold(root, { name, mode, force = false, quiet = false }) {
-  copyTemplate(path.join(PROJECT_ROOT, 'template'), root, {
+  const preserved = copyTemplate(path.join(PROJECT_ROOT, 'template'), root, {
     '{{PROJECT_NAME}}': name,
     '{{MODE}}': mode,
     '{{WORKSPACE_PATH}}': mode === 'embedded' ? '.' : '..',
@@ -124,12 +139,12 @@ function scaffold(root, { name, mode, force = false, quiet = false }) {
   // No se copia `.github/`: `ci.yml` valida el toolkit con `npm run ci` —que una instancia no tiene— y
   // el ciclo de aprendizaje dejó de distribuirse en 0.4.0. Copiar salteando lo que no aplica dejaba
   // `.github/workflows/` vacío en cada instancia.
-  copyRuntime(
+  Object.assign(preserved, copyRuntime(
     path.join(PROJECT_ROOT, 'automatization', 'hooks'),
     path.join(root, 'automatization', 'hooks'),
     force,
     root,
-  )
+  ))
   const version = require(path.join(PROJECT_ROOT, 'package.json')).version
   // El motor llega como dependencia para que el lockfile fije su versión. El repo ops es un sidecar:
   // declarar npm acá no convierte en Node al servicio de Go de al lado.
@@ -140,6 +155,14 @@ function scaffold(root, { name, mode, force = false, quiet = false }) {
     if (fs.existsSync(dir)) deliveredPaths = M.record(root, relative, O.treeFiles(dir), deliveredPaths)
   }
   deliveredPaths = M.recordPaths(root, O.SYSTEM_FILES, deliveredPaths)
+  // Lo conservado entra con el digest del molde, no con el del disco: la diferencia entre los dos es
+  // justamente lo que `localChanges` tiene que ver para que `upgrade` se detenga antes de pisar el
+  // archivo de la empresa. Sólo se pisan claves que ya están: el manifiesto declara lo que Cauce
+  // rastrea, y un archivo propio fuera de esa frontera no le incumbe.
+  for (const [file, hash] of Object.entries(preserved)) {
+    const relative = path.relative(root, file).split(path.sep).join('/')
+    if (relative in deliveredPaths) deliveredPaths[relative] = hash
+  }
   M.write(root, deliveredPaths)
   // La instancia recuerda de qué versión salió: sin esto no hay actualización posible.
   const configFile = path.join(root, 'ops.config.json')
@@ -305,12 +328,20 @@ function upgrade(dir, cli) {
   const overrides = O.overrides(root)
 
   if (dry) {
+    // Lo editado localmente se informa siempre, antes de mirar versiones: son dos preguntas distintas
+    // —«¿hay algo más nuevo?» y «¿qué tengo editado que se perdería?»— y la segunda tiene respuesta
+    // útil aunque la primera sea que no. Sin esto, el único modo que no toca nada era también el único
+    // que no podía avisar del conflicto, justo en el estado normal entre actualizaciones: `init` fija
+    // la versión exacta, así que instancia y motor coinciden casi todo el tiempo.
+    for (const file of changed) console.log(`  editado localmente: ${file}`)
     if (from === to) {
       // Contra el motor instalado, no contra lo publicado: la comparación es local y sin red. Decirlo
       // importa porque `init` fija la versión exacta, así que el motor no se mueve solo y esta línea,
       // a secas, se leía como «no hay nada nuevo» durante todas las versiones siguientes.
       console.log(`= ${to}: la instancia está al día con el motor instalado`)
-      return console.log('  para traer una versión más nueva: npm install --save-dev @ingeniomaps/cauce@latest')
+      console.log('  para traer una versión más nueva: npm install --save-dev @ingeniomaps/cauce@latest')
+      if (changed.length) process.exit(1)
+      return
     }
     // Hacia atrás también es legítimo —una versión rompió algo y se vuelve—, pero anunciarlo como «hay
     // una versión más nueva» era mentir con el número a la vista. Y lo que corresponde imprimir es lo
@@ -322,7 +353,6 @@ function upgrade(dir, cli) {
       console.log(`⚠ hay una versión más nueva: ${to} (la instancia tiene ${from || 'una previa'})`)
       printChangelog(from, to)
     }
-    for (const file of changed) console.log(`  editado localmente: ${file}`)
     process.exit(1)
   }
 
@@ -427,7 +457,10 @@ function upgrade(dir, cli) {
   for (const override of overrides) {
     console.log(`= conservado ${override.collection}/${override.project}: sobrescribe ${override.system}`)
   }
-  console.log('  planning, organization y todo lo propio quedaron intactos')
+  // Sólo cuando es cierto. Llegar acá con algo en `changed` significa que se corrió con --force y se
+  // descartó contenido de la empresa: las líneas de arriba lo enumeran, y afirmar a continuación que
+  // todo lo propio quedó intacto contradice a la única señal que recibe quien corrió el comando.
+  if (!changed.length) console.log('  planning, organization y todo lo propio quedaron intactos')
   // No se borra: sin la dependencia declarada, quitarle `.ops/` la dejaría sin motor. Se avisa y
   // decide una persona.
   if (fs.existsSync(path.join(root, '.ops', 'engine'))) {

package/engine/cli/ops.js

@@ -21,8 +21,14 @@ const DEFAULT_TARGET = 'ops'
 // de otra— y el proyecto quedaba llamándose «acme-ops». La carpeta que ya nombra al toolkit es la
 // instancia; no hay una segunda adentro.
 function implicitTarget(cwd) {
-  const base = path.basename(cwd)
-  return base === DEFAULT_TARGET || base.endsWith('-ops') ? '.' : DEFAULT_TARGET
+  return isInstanceDir(cwd) ? '.' : DEFAULT_TARGET
+}
+
+// La misma heurística, aplicada al destino ya resuelto: una carpeta que ya nombra al toolkit **es** la
+// instancia, y el código de la empresa vive al lado.
+function isInstanceDir(dir) {
+  const base = path.basename(dir)
+  return base === DEFAULT_TARGET || base.endsWith('-ops')
 }
 
 // El nombre sale de la carpeta del proyecto, no de la que aloja la instancia: `ops/` y `acme-ops/`
@@ -73,7 +79,12 @@ async function init(target, cli) {
   // install` ya asume —el wiring del runner va al padre, donde se abre la herramienta—, así que lo
   // único que faltaba era que fuera lo que pasa cuando no se elige nada.
   const root = path.resolve(target || implicitTarget(process.cwd()))
-  const mode = cli.value('--mode', target ? 'embedded' : 'sidecar')
+  // El modo lo decide a dónde apunta el destino, no si alguien escribió el argumento. `init` e `init .`
+  // resuelven el mismo directorio y elegían modos opuestos: escribir el punto —la forma más natural de
+  // decir «acá»— daba embedded, y ahí la raíz del workspace pasa a ser la carpeta ops misma, así que
+  // `guard-workspace-boundary` deja de reconocer los repos hermanos y el wiring del runner se escribe
+  // adentro en vez de al lado, donde el dev abre su herramienta.
+  const mode = cli.value('--mode', isInstanceDir(root) ? 'sidecar' : 'embedded')
   if (!['embedded', 'sidecar'].includes(mode)) fail('--mode debe ser embedded o sidecar.', 2)
   const name = cli.value('--name', defaultName(root))
   const force = cli.has('--force')

package/package.json

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