@ingeniomaps/cauce 0.55.0 → 0.56.0

package/CHANGELOG.md

@@ -14,6 +14,24 @@ 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.56.0] - 2026-09-03
+
+### Corregido
+
+- **El upgrade que documentaba el README rompía el pin exacto que puso `init`.** La razón para no
+  saltear su primer paso es que «`init` fija la versión exacta, así que `npm update` no la mueve», y
+  el comando de al lado la desarmaba: npm guarda con caret por defecto, así que
+  `npm install --save-dev @ingeniomaps/cauce@latest` dejaba `^0.55.0`, y dentro de `0.x` ese caret
+  alcanza a los patches —que Cauce publica—. Un `npm install` en otra máquina podía dejar el motor en
+  una versión que `ops.config.json` no decía.
+
+  Se arregla por los dos lados. El comando lleva `--save-exact` en los tres lugares que lo dictan —el
+  README, el `make upgrade` de tu instancia y la salida de `upgrade --check`—, y además **`upgrade`
+  repone la versión exacta al terminar**, así que una instancia que ya quedó con un rango se repara
+  sola en la próxima actualización. **Qué cambia para vos**: `upgrade` puede tocar ahora una línea de
+  tu `package.json`, y lo dice cuando lo hace. El resto del manifiesto queda como estaba, y una
+  instancia sin `package.json` no recibe uno.
+
 ## [0.55.0] - 2026-09-02
 
 ### Corregido

package/README.md

@@ -266,13 +266,15 @@ existente detiene el `upgrade` antes de pisarlo.
 Son tres pasos y `make upgrade` hace los dos primeros:
 
 ```bash
-npm install --save-dev @ingeniomaps/cauce@latest   # trae el motor nuevo
+npm install --save-exact --save-dev @ingeniomaps/cauce@latest   # trae el motor nuevo
 node tools/ops.js upgrade .                        # aplica system/ y el runtime
 node tools/ops.js automation install . claude      # el wiring del runner
 ```
 
 El primero no se puede saltear: `init` fija la versión exacta, así que `npm update` no la mueve y
-`upgrade` compara contra el motor instalado —lo dice en su salida—. El tercero tampoco: los workflows y
+`upgrade` compara contra el motor instalado —lo dice en su salida—. Va con `--save-exact` porque npm
+guarda con caret por defecto, y ese caret es justamente lo que volvería falsa la frase anterior; si
+alguna vez se instaló sin él, `upgrade` repone la versión exacta al terminar. El tercero tampoco: los workflows y
 las skills viven en el runner, no en la instancia, y `upgrade` no los toca. `upgrade` lo recuerda al
 terminar.
 

package/engine/cli/dependency.js

@@ -0,0 +1,73 @@
+'use strict'
+
+// Cómo una instancia declara el motor en su `package.json`: ponerlo, reponerlo y sacarlo. Vive aparte
+// del ciclo de vida porque su reloj es otro —npm y el versionado, no crear/actualizar/borrar— y porque
+// sus tres consumidores no se solapan: `scaffold` declara, `upgrade` repone y `destroy` saca.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const F = require('../core/files')
+const { fail } = require('./io')
+
+// Declara el motor como dependencia exacta: el lockfile decide qué versión corre, no una copia.
+// Conserva el manifiesto existente porque el repo anfitrión puede tener el suyo.
+function declareEngine(manifest, version) {
+  let pkg = { name: path.basename(path.dirname(manifest)), private: true, version: '0.0.0' }
+  if (fs.existsSync(manifest)) {
+    try { pkg = JSON.parse(fs.readFileSync(manifest, 'utf8')) } catch (error) {
+      fail(`package.json inválido en ${manifest}: ${error.message}`)
+    }
+  }
+  pkg.devDependencies = { ...pkg.devDependencies, '@ingeniomaps/cauce': version }
+  F.atomicWriteJson(manifest, pkg)
+}
+
+// Repone la versión exacta que `declareEngine` había dejado, y devuelve la que había si cambió algo.
+//
+// El pin no sobrevive por sí solo: npm guarda con caret, así que el `npm install @latest` del primer
+// paso del upgrade lo convierte en un rango, y con eso deja de valer la razón que el README da para no
+// saltear ese paso —«init fija la versión exacta, así que npm update no la mueve»—. Repararlo acá y no
+// sólo documentar el comando es lo que vuelve la propiedad independiente de cómo se haya instalado.
+//
+// Sin manifiesto no hay nada que reponer: una instancia que no lo tiene resuelve el motor de otra
+// forma, y crearle uno sería otra operación que nadie pidió en un upgrade.
+function pinEngine(root, version) {
+  const manifest = path.join(root, 'package.json')
+  if (!fs.existsSync(manifest)) return null
+  let pkg
+  try { pkg = JSON.parse(fs.readFileSync(manifest, 'utf8')) } catch { return 'ilegible' }
+  const current = (pkg.devDependencies || {})['@ingeniomaps/cauce']
+  if (!current || current === version) return null
+  declareEngine(manifest, version)
+  return current
+}
+
+// La inversa exacta de `declareEngine`: saca la clave que puso y nada más. El resto del manifiesto es
+// del repo anfitrión aunque hoy no tenga otra cosa —un `package.json` vacío puede ser lo que alguien
+// escribió para tener scripts— así que el archivo se borra sólo si es idéntico al que `declareEngine`
+// habría creado desde cero, sin dependencias, sin scripts y con su `version: 0.0.0`.
+//
+// Lo que no se toca nunca es `node_modules/` ni el lockfile: los escribe npm, pueden tener dependencias
+// del proyecto y borrarlos por nuestra cuenta destruye trabajo ajeno. Se nombran en la salida, que es
+// la mitad que faltaba: `destroy` decía «tu repositorio queda donde está» y dejaba un `package.json`
+// cuya única dependencia era Cauce. En un repo Rust eso es basura conspicua y nadie avisaba.
+function undeclareEngine(manifest) {
+  if (!fs.existsSync(manifest)) return []
+  let pkg
+  try { pkg = JSON.parse(fs.readFileSync(manifest, 'utf8')) } catch { return [] }
+  const dev = pkg.devDependencies || {}
+  if (!('@ingeniomaps/cauce' in dev)) return []
+  delete dev['@ingeniomaps/cauce']
+  pkg.devDependencies = dev
+  const ours = !Object.keys(dev).length && !Object.keys(pkg.dependencies || {}).length
+    && !Object.keys(pkg.scripts || {}).length && pkg.private === true && pkg.version === '0.0.0'
+  if (ours) {
+    fs.rmSync(manifest, { force: true })
+    return ['package.json (lo había creado init: sin dependencias ni scripts propios)']
+  }
+  if (!Object.keys(dev).length) delete pkg.devDependencies
+  F.atomicWriteJson(manifest, pkg)
+  return ['package.json: se quitó la dependencia del motor y el resto queda como estaba']
+}
+
+module.exports = { declareEngine, pinEngine, undeclareEngine }

package/engine/cli/instance.js

@@ -16,6 +16,7 @@ const P = require('../planning/parser')
 const ST = require('../planning/state')
 const A = require('../automation')
 const { fail } = require('./io')
+const { declareEngine, pinEngine, undeclareEngine } = require('./dependency')
 
 const PROJECT_ROOT = path.resolve(__dirname, '..', '..')
 
@@ -86,47 +87,6 @@ function copyRuntime(source, target, preserve = false, boundary = target, skip =
   return preserved
 }
 
-// Declara el motor como dependencia exacta: el lockfile decide qué versión corre, no una copia.
-// Conserva el manifiesto existente porque el repo anfitrión puede tener el suyo.
-function declareEngine(manifest, version) {
-  let pkg = { name: path.basename(path.dirname(manifest)), private: true, version: '0.0.0' }
-  if (fs.existsSync(manifest)) {
-    try { pkg = JSON.parse(fs.readFileSync(manifest, 'utf8')) } catch (error) {
-      fail(`package.json inválido en ${manifest}: ${error.message}`)
-    }
-  }
-  pkg.devDependencies = { ...pkg.devDependencies, '@ingeniomaps/cauce': version }
-  F.atomicWriteJson(manifest, pkg)
-}
-
-// La inversa exacta de `declareEngine`: saca la clave que puso y nada más. El resto del manifiesto es
-// del repo anfitrión aunque hoy no tenga otra cosa —un `package.json` vacío puede ser lo que alguien
-// escribió para tener scripts— así que el archivo se borra sólo si es idéntico al que `declareEngine`
-// habría creado desde cero, sin dependencias, sin scripts y con su `version: 0.0.0`.
-//
-// Lo que no se toca nunca es `node_modules/` ni el lockfile: los escribe npm, pueden tener dependencias
-// del proyecto y borrarlos por nuestra cuenta destruye trabajo ajeno. Se nombran en la salida, que es
-// la mitad que faltaba: `destroy` decía «tu repositorio queda donde está» y dejaba un `package.json`
-// cuya única dependencia era Cauce. En un repo Rust eso es basura conspicua y nadie avisaba.
-function undeclareEngine(manifest) {
-  if (!fs.existsSync(manifest)) return []
-  let pkg
-  try { pkg = JSON.parse(fs.readFileSync(manifest, 'utf8')) } catch { return [] }
-  const dev = pkg.devDependencies || {}
-  if (!('@ingeniomaps/cauce' in dev)) return []
-  delete dev['@ingeniomaps/cauce']
-  pkg.devDependencies = dev
-  const ours = !Object.keys(dev).length && !Object.keys(pkg.dependencies || {}).length
-    && !Object.keys(pkg.scripts || {}).length && pkg.private === true && pkg.version === '0.0.0'
-  if (ours) {
-    fs.rmSync(manifest, { force: true })
-    return ['package.json (lo había creado init: sin dependencias ni scripts propios)']
-  }
-  if (!Object.keys(dev).length) delete pkg.devDependencies
-  F.atomicWriteJson(manifest, pkg)
-  return ['package.json: se quitó la dependencia del motor y el resto queda como estaba']
-}
-
 // El andamiaje de una instancia, sin leer argv. `init` es la cáscara que traduce banderas a esto, y
 // 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.
@@ -339,7 +299,10 @@ function upgrade(dir, cli) {
       // 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`)
-      console.log('  para traer una versión más nueva: npm install --save-dev @ingeniomaps/cauce@latest')
+      // Con `--save-exact` porque npm guarda con caret por defecto, y el caret es lo que volvería
+      // falsa la línea de arriba: dentro de 0.x alcanza a los patches, y Cauce publica patches.
+      console.log('  para traer una versión más nueva:'
+        + ' npm install --save-exact --save-dev @ingeniomaps/cauce@latest')
       if (changed.length) process.exit(1)
       return
     }
@@ -446,12 +409,18 @@ function upgrade(dir, cli) {
   const config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))
   config.cauceVersion = to
   F.atomicWriteJson(path.join(root, 'ops.config.json'), config)
+  // Acá es donde las tres versiones se saben a la vez, así que es donde pueden quedar diciendo lo mismo.
+  const pinned = pinEngine(root, to)
 
   console.log(`✓ Cauce ${from || '(previa)'} → ${to}`)
   // Descartar con --force es legítimo; hacerlo sin dejar rastro no. Queda en la salida del comando,
   // que es la evidencia que el protocolo pide para cualquier cambio.
   for (const file of changed) console.log(`− descartado tu cambio en ${file}`)
   for (const relative of retired) console.log(`− retirado ${relative}: Cauce ya no lo distribuye`)
+  // Se dice porque cambia un archivo que la empresa versiona, y porque explica un diff que si no
+  // aparecería sin autor. Ilegible se avisa y no se toca: el manifiesto es del repo anfitrión.
+  if (pinned === 'ilegible') console.log('  ⚠ package.json no se pudo leer: su versión quedó como estaba')
+  else if (pinned) console.log(`  package.json: ${pinned} → ${to}, la versión exacta que acabás de aplicar`)
   printChangelog(from, to)
   console.log(`  ${system.length} ruta(s) del sistema y ${O.RUNTIME_PATHS.length} del runtime actualizadas`)
   for (const override of overrides) {

package/package.json

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

package/template/Makefile

@@ -29,7 +29,7 @@ destroy: ## Muestra qué se pierde al borrar esta instancia (borrar exige --forc
 	@node tools/ops.js destroy .
 
 upgrade: ## Trae la última versión de Cauce y la aplica, sin tocar lo del proyecto
-	@npm install --save-dev @ingeniomaps/cauce@latest
+	@npm install --save-exact --save-dev @ingeniomaps/cauce@latest
 	@node tools/ops.js upgrade .
 
 automation-check: ## Comprueba hooks, workflows y adaptadores