@saulwade/swl-ses 2.6.0 → 2.8.0

package/scripts/lib/ciclo-autonomo/config.js

@@ -1,165 +1,165 @@
-'use strict';
-
-/**
- * Loader/writer de `.planning/evolution/ciclo-config.json` — schema del
- * motor determinista de aprendizaje (Fase 21, ADR-0041/ADR-0042, Nivel 0).
- *
- * Opt-OUT estricto (decisión del usuario 2026-07-10, reformula la regla de
- * negocio 1 de la Fase 21): el motor NACE ENCENDIDO — "un ciclo que exige
- * encendido es un ciclo muerto en downstream". Kill-switch doble:
- * `habilitado:false` en el config (vía `/swl:evolucion-continua off`) o
- * `SWL_CICLO_AUTONOMO=0` por sesión. Esta lib solo expone el predicado
- * `estaHabilitado()`; el único punto que lo consulta para decidir si
- * ejecutar es el orquestador (T-07, `index.js`) — las libs de sub-fase
- * (writer, drenador, puente) son puras y no consultan config.
- *
- * Zero-deps, CommonJS.
- *
- * @module scripts/lib/ciclo-autonomo/config
- */
-
-const fs = require('fs');
-const path = require('path');
-const { atomicWriteJSON } = require('../../../hooks/lib/atomic-write');
-
-/** Ruta relativa del archivo de config dentro del baseDir del proyecto. */
-const CONFIG_RELATIVA = path.join('.planning', 'evolution', 'ciclo-config.json');
-
-/** Valores aceptados para el campo `credencial` (dual: cuenta Claude o API key). */
-const CREDENCIALES_VALIDAS = new Set(['cuenta', 'api-key']);
-
-/**
- * Defaults del schema completo. Los campos LLM (`presupuesto_usd_mes`,
- * `tope_mutaciones_corrida`) nacieron reservados en Fase 21 y se consumen a
- * partir de Fase 22. Los campos `fase_b_habilitada`, `last_run_fase_b`,
- * `gasto_mes`, `mes` y `pausado_por_presupuesto` son propios de Fase 22
- * (headless plumbing, ADR-0042 gate G-B): `fase_b_habilitada` nace en `true`
- * —kill-switch separado del motor, coherente con el opt-out estricto general
- * (default encendido)—; `gasto_mes`/`mes` llevan el contador de presupuesto
- * del mes en curso (clave `mes` en formato `YYYY-MM` local); `mes:null`
- * fuerza el primer `registrarGasto` a inicializar el mes actual.
- */
-const DEFAULTS = Object.freeze({
-  habilitado: true,
-  credencial: 'cuenta',
-  presupuesto_usd_mes: 10,
-  tope_mutaciones_corrida: 3,
-  last_run: null,
-  ultima_corrida: null,
-  fase_b_habilitada: true,
-  last_run_fase_b: null,
-  gasto_mes: 0,
-  mes: null,
-  pausado_por_presupuesto: false,
-});
-
-/**
- * Resuelve la ruta absoluta del archivo de config para un baseDir dado.
- *
- * @param {string} baseDir - Directorio raíz del proyecto (normalmente cwd).
- * @returns {string} Ruta absoluta a `ciclo-config.json`.
- */
-function rutaConfig(baseDir) {
-  return path.join(baseDir, CONFIG_RELATIVA);
-}
-
-/**
- * Normaliza el campo `credencial`: valor fuera del dominio válido cae a
- * "cuenta" sin lanzar error — un config corrupto o editado a mano nunca
- * debe crashear al motor.
- *
- * @param {*} valor - Valor crudo leído de disco o de un patch.
- * @returns {"cuenta"|"api-key"}
- */
-function normalizarCredencial(valor) {
-  return CREDENCIALES_VALIDAS.has(valor) ? valor : 'cuenta';
-}
-
-/**
- * Lee el config del disco y lo mergea con los defaults del schema.
- *
- * Tolerante a archivo ausente (proyecto nunca habilitó el ciclo) y a JSON
- * corrupto (config editado a mano incorrectamente) — en ambos casos cae
- * a los defaults en vez de lanzar.
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- * @returns {object} Config completo con todos los campos del schema.
- */
-function leerConfig(baseDir) {
-  const ruta = rutaConfig(baseDir);
-  let crudo = {};
-
-  try {
-    const contenido = fs.readFileSync(ruta, 'utf8');
-    crudo = JSON.parse(contenido);
-  } catch (_) {
-    // Archivo ausente o JSON corrupto: se opera con los defaults.
-    crudo = {};
-  }
-
-  const mergeado = { ...DEFAULTS, ...crudo };
-  mergeado.credencial = normalizarCredencial(mergeado.credencial);
-  return mergeado;
-}
-
-/**
- * Escribe un patch sobre el config existente (merge, no overwrite) y lo
- * persiste de forma atómica. Crea `.planning/evolution/` si falta.
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- * @param {object} patch   - Campos a actualizar; el resto se preserva.
- * @returns {object} Config final ya escrito a disco.
- */
-function escribirConfig(baseDir, patch) {
-  const actual = leerConfig(baseDir);
-  const siguiente = { ...actual, ...patch };
-  siguiente.credencial = normalizarCredencial(siguiente.credencial);
-
-  const ruta = rutaConfig(baseDir);
-  const dir = path.dirname(ruta);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-
-  atomicWriteJSON(ruta, siguiente);
-  return siguiente;
-}
-
-/**
- * Predicado de encendido del ciclo autónomo — opt-OUT estricto (decisión
- * del usuario 2026-07-10): el motor nace ENCENDIDO; se apaga con
- * `habilitado:false` en el config (`/swl:evolucion-continua off`) o con
- * `SWL_CICLO_AUTONOMO=0` por sesión. `SWL_CICLO_AUTONOMO=1` fuerza el
- * encendido por encima de un `off` en disco (override operacional en
- * CI/cron sin tocar el archivo).
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- * @returns {boolean}
- */
-function estaHabilitado(baseDir) {
-  if (process.env.SWL_CICLO_AUTONOMO === '0') return false;
-  if (process.env.SWL_CICLO_AUTONOMO === '1') return true;
-  return leerConfig(baseDir).habilitado !== false;
-}
-
-/**
- * Predicado de encendido de la Fase B (detector + runner headless,
- * Fase 22) — kill-switch separado del motor general, pero SUBORDINADO a él
- * (regla de negocio 1: motor apagado ⇒ Fase B apagada, sin excepción). Fase B
- * no agrega variable de entorno propia: hereda `SWL_CICLO_AUTONOMO` a través
- * de `estaHabilitado`.
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- * @returns {boolean}
- */
-function estaFaseBHabilitada(baseDir) {
-  if (!estaHabilitado(baseDir)) return false;
-  return leerConfig(baseDir).fase_b_habilitada !== false;
-}
-
-module.exports = {
-  estaHabilitado,
-  estaFaseBHabilitada,
-  leerConfig,
-  escribirConfig,
-};
+'use strict';
+
+/**
+ * Loader/writer de `.planning/evolution/ciclo-config.json` — schema del
+ * motor determinista de aprendizaje (Fase 21, ADR-0041/ADR-0042, Nivel 0).
+ *
+ * Opt-OUT estricto (decisión del usuario 2026-07-10, reformula la regla de
+ * negocio 1 de la Fase 21): el motor NACE ENCENDIDO — "un ciclo que exige
+ * encendido es un ciclo muerto en downstream". Kill-switch doble:
+ * `habilitado:false` en el config (vía `/swl:evolucion-continua off`) o
+ * `SWL_CICLO_AUTONOMO=0` por sesión. Esta lib solo expone el predicado
+ * `estaHabilitado()`; el único punto que lo consulta para decidir si
+ * ejecutar es el orquestador (T-07, `index.js`) — las libs de sub-fase
+ * (writer, drenador, puente) son puras y no consultan config.
+ *
+ * Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/config
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWriteJSON } = require('../../../hooks/lib/atomic-write');
+
+/** Ruta relativa del archivo de config dentro del baseDir del proyecto. */
+const CONFIG_RELATIVA = path.join('.planning', 'evolution', 'ciclo-config.json');
+
+/** Valores aceptados para el campo `credencial` (dual: cuenta Claude o API key). */
+const CREDENCIALES_VALIDAS = new Set(['cuenta', 'api-key']);
+
+/**
+ * Defaults del schema completo. Los campos LLM (`presupuesto_usd_mes`,
+ * `tope_mutaciones_corrida`) nacieron reservados en Fase 21 y se consumen a
+ * partir de Fase 22. Los campos `fase_b_habilitada`, `last_run_fase_b`,
+ * `gasto_mes`, `mes` y `pausado_por_presupuesto` son propios de Fase 22
+ * (headless plumbing, ADR-0042 gate G-B): `fase_b_habilitada` nace en `true`
+ * —kill-switch separado del motor, coherente con el opt-out estricto general
+ * (default encendido)—; `gasto_mes`/`mes` llevan el contador de presupuesto
+ * del mes en curso (clave `mes` en formato `YYYY-MM` local); `mes:null`
+ * fuerza el primer `registrarGasto` a inicializar el mes actual.
+ */
+const DEFAULTS = Object.freeze({
+  habilitado: true,
+  credencial: 'cuenta',
+  presupuesto_usd_mes: 10,
+  tope_mutaciones_corrida: 3,
+  last_run: null,
+  ultima_corrida: null,
+  fase_b_habilitada: true,
+  last_run_fase_b: null,
+  gasto_mes: 0,
+  mes: null,
+  pausado_por_presupuesto: false,
+});
+
+/**
+ * Resuelve la ruta absoluta del archivo de config para un baseDir dado.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto (normalmente cwd).
+ * @returns {string} Ruta absoluta a `ciclo-config.json`.
+ */
+function rutaConfig(baseDir) {
+  return path.join(baseDir, CONFIG_RELATIVA);
+}
+
+/**
+ * Normaliza el campo `credencial`: valor fuera del dominio válido cae a
+ * "cuenta" sin lanzar error — un config corrupto o editado a mano nunca
+ * debe crashear al motor.
+ *
+ * @param {*} valor - Valor crudo leído de disco o de un patch.
+ * @returns {"cuenta"|"api-key"}
+ */
+function normalizarCredencial(valor) {
+  return CREDENCIALES_VALIDAS.has(valor) ? valor : 'cuenta';
+}
+
+/**
+ * Lee el config del disco y lo mergea con los defaults del schema.
+ *
+ * Tolerante a archivo ausente (proyecto nunca habilitó el ciclo) y a JSON
+ * corrupto (config editado a mano incorrectamente) — en ambos casos cae
+ * a los defaults en vez de lanzar.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {object} Config completo con todos los campos del schema.
+ */
+function leerConfig(baseDir) {
+  const ruta = rutaConfig(baseDir);
+  let crudo = {};
+
+  try {
+    const contenido = fs.readFileSync(ruta, 'utf8');
+    crudo = JSON.parse(contenido);
+  } catch (_) {
+    // Archivo ausente o JSON corrupto: se opera con los defaults.
+    crudo = {};
+  }
+
+  const mergeado = { ...DEFAULTS, ...crudo };
+  mergeado.credencial = normalizarCredencial(mergeado.credencial);
+  return mergeado;
+}
+
+/**
+ * Escribe un patch sobre el config existente (merge, no overwrite) y lo
+ * persiste de forma atómica. Crea `.planning/evolution/` si falta.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {object} patch   - Campos a actualizar; el resto se preserva.
+ * @returns {object} Config final ya escrito a disco.
+ */
+function escribirConfig(baseDir, patch) {
+  const actual = leerConfig(baseDir);
+  const siguiente = { ...actual, ...patch };
+  siguiente.credencial = normalizarCredencial(siguiente.credencial);
+
+  const ruta = rutaConfig(baseDir);
+  const dir = path.dirname(ruta);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  atomicWriteJSON(ruta, siguiente);
+  return siguiente;
+}
+
+/**
+ * Predicado de encendido del ciclo autónomo — opt-OUT estricto (decisión
+ * del usuario 2026-07-10): el motor nace ENCENDIDO; se apaga con
+ * `habilitado:false` en el config (`/swl:evolucion-continua off`) o con
+ * `SWL_CICLO_AUTONOMO=0` por sesión. `SWL_CICLO_AUTONOMO=1` fuerza el
+ * encendido por encima de un `off` en disco (override operacional en
+ * CI/cron sin tocar el archivo).
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {boolean}
+ */
+function estaHabilitado(baseDir) {
+  if (process.env.SWL_CICLO_AUTONOMO === '0') return false;
+  if (process.env.SWL_CICLO_AUTONOMO === '1') return true;
+  return leerConfig(baseDir).habilitado !== false;
+}
+
+/**
+ * Predicado de encendido de la Fase B (detector + runner headless,
+ * Fase 22) — kill-switch separado del motor general, pero SUBORDINADO a él
+ * (regla de negocio 1: motor apagado ⇒ Fase B apagada, sin excepción). Fase B
+ * no agrega variable de entorno propia: hereda `SWL_CICLO_AUTONOMO` a través
+ * de `estaHabilitado`.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {boolean}
+ */
+function estaFaseBHabilitada(baseDir) {
+  if (!estaHabilitado(baseDir)) return false;
+  return leerConfig(baseDir).fase_b_habilitada !== false;
+}
+
+module.exports = {
+  estaHabilitado,
+  estaFaseBHabilitada,
+  leerConfig,
+  escribirConfig,
+};