@saulwade/swl-ses 1.3.7 → 1.4.0

package/gateway/cron/scheduler.js

@@ -0,0 +1,322 @@
+'use strict';
+
+/**
+ * Cron Scheduler — Tick loop para ejecución de jobs programados.
+ *
+ * Inspirado en Hermes Agent (cron/scheduler.py):
+ *   - File lock exclusivo para prevenir ejecución concurrente
+ *   - Tick cada 60 segundos
+ *   - Grace windows para jobs retrasados
+ *   - Entrega de resultados local o vía gateway
+ *
+ * Uso:
+ *   node gateway/cron/scheduler.js [baseDir]
+ *
+ * También exporta funciones para uso programático desde otros módulos.
+ *
+ * @module gateway/cron/scheduler
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const { loadJobs, markExecuted, updateAgentState } = require('./store');
+const { isEligible } = require('./jobs');
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+/** Intervalo entre ticks en milisegundos. */
+const TICK_INTERVAL_MS = 60000;
+
+/** Nombre del archivo de lock. */
+const LOCK_FILENAME = '.tick.lock';
+
+/** Timeout de ejecución de un job individual (5 minutos). */
+const JOB_TIMEOUT_MS = 300000;
+
+// ---------------------------------------------------------------------------
+// File lock (cross-platform)
+// ---------------------------------------------------------------------------
+
+let _lockFd = null;
+let _lockPath = null;
+
+/**
+ * Adquiere un lock exclusivo basado en archivo.
+ * Previene múltiples instancias del scheduler ejecutándose simultáneamente.
+ *
+ * @param {string} baseDir
+ * @returns {boolean} true si se adquirió el lock, false si ya está tomado.
+ */
+function acquireLock(baseDir) {
+  const cronDir = path.join(baseDir, '.planning', 'cron');
+  if (!fs.existsSync(cronDir)) fs.mkdirSync(cronDir, { recursive: true });
+
+  _lockPath = path.join(cronDir, LOCK_FILENAME);
+
+  try {
+    // O_WRONLY | O_CREAT | O_EXCL — falla si el archivo ya existe
+    _lockFd = fs.openSync(_lockPath, 'wx');
+    fs.writeSync(_lockFd, `${process.pid}\n${new Date().toISOString()}\n`);
+    return true;
+  } catch (err) {
+    if (err.code === 'EEXIST') {
+      // Lock ya existe — verificar si el proceso que lo creó sigue vivo
+      try {
+        const content = fs.readFileSync(_lockPath, 'utf8');
+        const pid = parseInt(content.split('\n')[0], 10);
+        if (pid && _isProcessAlive(pid)) {
+          return false; // Otro proceso lo tiene
+        }
+        // Proceso muerto — robar el lock
+        fs.unlinkSync(_lockPath);
+        return acquireLock(baseDir); // Reintentar
+      } catch (_) {
+        return false;
+      }
+    }
+    return false;
+  }
+}
+
+/**
+ * Libera el lock.
+ */
+function releaseLock() {
+  if (_lockFd !== null) {
+    try { fs.closeSync(_lockFd); } catch (e) { /* fd ya cerrado */ }
+    _lockFd = null;
+  }
+  if (_lockPath) {
+    try { fs.unlinkSync(_lockPath); } catch (e) { /* lock ya eliminado */ }
+    _lockPath = null;
+  }
+}
+
+function _isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0); // Signal 0 = check existence
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Ejecución de jobs
+// ---------------------------------------------------------------------------
+
+/**
+ * Ejecuta un job individual.
+ *
+ * @param {object} job - Job a ejecutar.
+ * @param {string} baseDir
+ * @returns {{ status: string, output: string }}
+ */
+function executeJob(job, baseDir) {
+  const command = job.command;
+  if (!command) {
+    return { status: 'error', output: 'Job sin comando definido' };
+  }
+
+  try {
+    const output = execSync(command, {
+      cwd: baseDir,
+      encoding: 'utf8',
+      timeout: JOB_TIMEOUT_MS,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        SWL_CRON_JOB_ID: job.id,
+        SWL_CRON_JOB_NAME: job.name,
+      },
+    });
+
+    return { status: 'completed', output: output.trim() };
+  } catch (err) {
+    const output = err.stdout ? err.stdout.toString() : err.message;
+    const stderr = err.stderr ? err.stderr.toString() : '';
+    return {
+      status: 'error',
+      output: `${output}\n${stderr}`.trim().substring(0, 2000),
+    };
+  }
+}
+
+/**
+ * Entrega el resultado de un job al destino configurado.
+ *
+ * @param {object} job    - Job ejecutado.
+ * @param {object} result - Resultado de executeJob.
+ * @param {string} baseDir
+ */
+function deliverResult(job, result, baseDir) {
+  const deliver = job.deliver || 'local';
+
+  if (deliver === 'local') {
+    // Guardar en .planning/cron/output/{jobId}/
+    const outputDir = path.join(baseDir, '.planning', 'cron', 'output', job.id);
+    if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const filePath  = path.join(outputDir, `${timestamp}.md`);
+
+    const content = [
+      `# Cron: ${job.name}`,
+      ``,
+      `**Job ID**: ${job.id}`,
+      `**Ejecutado**: ${new Date().toISOString()}`,
+      `**Comando**: \`${job.command}\``,
+      `**Estado**: ${result.status}`,
+      ``,
+      '## Output',
+      '```',
+      result.output || '(sin output)',
+      '```',
+    ].join('\n');
+
+    try {
+      const { atomicWriteSync } = require('../../hooks/lib/atomic-write');
+      atomicWriteSync(filePath, content);
+    } catch (_) {
+      fs.writeFileSync(filePath, content, 'utf8');
+    }
+    return;
+  }
+
+  // Entrega vía gateway (telegram, discord, webhook)
+  // Escribir en agent-comms para que el gateway lo recoja
+  try {
+    const { enviarMensaje } = require('../../hooks/lib/agent-comms');
+    enviarMensaje(baseDir, {
+      type: 'gateway_notification',
+      from: 'cron-scheduler',
+      to: deliver,
+      payload: {
+        jobId: job.id,
+        jobName: job.name,
+        status: result.status,
+        output: result.output?.substring(0, 1000),
+      },
+    });
+  } catch (_) {
+    // Si agent-comms falla, guardar localmente como fallback
+    deliverResult({ ...job, deliver: 'local' }, result, baseDir);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tick
+// ---------------------------------------------------------------------------
+
+/**
+ * Ejecuta un tick del scheduler: evalúa y ejecuta jobs elegibles.
+ *
+ * @param {string} baseDir
+ * @returns {{ executed: number, errors: number }}
+ */
+function tick(baseDir) {
+  const jobs = loadJobs(baseDir);
+  const now  = new Date();
+  let executed = 0;
+  let errors   = 0;
+
+  for (const job of jobs) {
+    if (!isEligible(job, now)) continue;
+
+    const result = executeJob(job, baseDir);
+    markExecuted(baseDir, job.id, result);
+    updateAgentState(baseDir, job.id, result); // state-per-agent: consecutiveErrors, runCount
+    deliverResult(job, result, baseDir);
+
+    if (result.status === 'completed') {
+      executed++;
+    } else {
+      errors++;
+    }
+  }
+
+  return { executed, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Scheduler loop
+// ---------------------------------------------------------------------------
+
+let _intervalId = null;
+
+/**
+ * Inicia el scheduler loop.
+ *
+ * @param {string} baseDir
+ * @returns {boolean} true si se inició, false si ya hay uno corriendo.
+ */
+function startScheduler(baseDir) {
+  if (!acquireLock(baseDir)) {
+    return false;
+  }
+
+  // Registrar cleanup
+  const cleanup = () => {
+    stopScheduler();
+    process.exit(0);
+  };
+  process.on('SIGTERM', cleanup);
+  process.on('SIGINT', cleanup);
+
+  // Tick inicial
+  tick(baseDir);
+
+  // Loop
+  _intervalId = setInterval(() => tick(baseDir), TICK_INTERVAL_MS);
+
+  return true;
+}
+
+/**
+ * Detiene el scheduler y libera el lock.
+ */
+function stopScheduler() {
+  if (_intervalId !== null) {
+    clearInterval(_intervalId);
+    _intervalId = null;
+  }
+  releaseLock();
+}
+
+// ---------------------------------------------------------------------------
+// Entrypoint CLI
+// ---------------------------------------------------------------------------
+
+if (require.main === module) {
+  const baseDir = process.argv[2] || process.cwd();
+
+  console.log(`[cron-scheduler] Iniciando en ${baseDir}`);
+  console.log(`[cron-scheduler] Tick interval: ${TICK_INTERVAL_MS / 1000}s`);
+
+  const started = startScheduler(baseDir);
+  if (!started) {
+    console.error('[cron-scheduler] Otro scheduler ya está corriendo. Saliendo.');
+    process.exit(1);
+  }
+
+  console.log('[cron-scheduler] Scheduler activo. Ctrl+C para detener.');
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  tick,
+  startScheduler,
+  stopScheduler,
+  executeJob,
+  deliverResult,
+  acquireLock,
+  releaseLock,
+  TICK_INTERVAL_MS,
+};

package/gateway/cron/store.js

@@ -0,0 +1,335 @@
+'use strict';
+
+/**
+ * Cron Store — Persistencia de jobs CRON en JSON.
+ *
+ * Almacena jobs en .planning/cron/jobs.json con escritura atómica.
+ * Cada job tiene: id, name, schedule, command, deliver, status, nextRun, lastRunAt.
+ *
+ * @module gateway/cron/store
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { atomicWriteJSON } = require('../../hooks/lib/atomic-write');
+const { parseSchedule, computeNextRun } = require('./jobs');
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+const CRON_DIR        = '.planning/cron';
+const JOBS_FILE       = 'jobs.json';
+const LOG_FILE        = 'log.json';
+const AGENT_STATE_FILE = 'agent-state.json';
+const MAX_LOG_ENTRIES = 500;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function ensureDir(baseDir) {
+  const dir = path.join(baseDir, CRON_DIR);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function jobsPath(baseDir) {
+  return path.join(ensureDir(baseDir), JOBS_FILE);
+}
+
+function logPath(baseDir) {
+  return path.join(ensureDir(baseDir), LOG_FILE);
+}
+
+function agentStatePath(baseDir) {
+  return path.join(ensureDir(baseDir), AGENT_STATE_FILE);
+}
+
+// ---------------------------------------------------------------------------
+// CRUD de jobs
+// ---------------------------------------------------------------------------
+
+/**
+ * Carga todos los jobs.
+ * @param {string} baseDir
+ * @returns {object[]}
+ */
+function loadJobs(baseDir) {
+  const p = jobsPath(baseDir);
+  try {
+    if (!fs.existsSync(p)) return [];
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * Persiste todos los jobs atómicamente.
+ * @param {string} baseDir
+ * @param {object[]} jobs
+ */
+function saveJobs(baseDir, jobs) {
+  atomicWriteJSON(jobsPath(baseDir), jobs);
+}
+
+/**
+ * Agrega un job nuevo.
+ *
+ * @param {string} baseDir
+ * @param {object} opts
+ * @param {string} opts.name     - Nombre descriptivo.
+ * @param {string} opts.schedule - Schedule string (ej: "every 2h", "0 9 * * 1-5").
+ * @param {string} opts.command  - Comando a ejecutar.
+ * @param {string} [opts.deliver='local'] - Destino: "local", "telegram", "discord".
+ * @param {boolean} [opts.enabled=true]
+ * @returns {object} Job creado.
+ */
+function addJob(baseDir, opts) {
+  const jobs = loadJobs(baseDir);
+
+  const parsed = parseSchedule(opts.schedule);
+  const id = `cron-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+
+  const job = {
+    id,
+    name:           opts.name,
+    schedule:       opts.schedule,
+    parsedSchedule: parsed,
+    command:        opts.command,
+    deliver:        opts.deliver || 'local',
+    status:         opts.enabled !== false ? 'scheduled' : 'paused',
+    nextRun:        null,
+    lastRunAt:      null,
+    createdAt:      new Date().toISOString(),
+    repeat:         parsed.kind === 'once' ? { times: 1, completed: 0 } : null,
+  };
+
+  // Calcular próxima ejecución
+  job.nextRun = computeNextRun(job);
+
+  jobs.push(job);
+  saveJobs(baseDir, jobs);
+  return job;
+}
+
+/**
+ * Elimina un job por ID.
+ * @param {string} baseDir
+ * @param {string} jobId
+ * @returns {boolean}
+ */
+function removeJob(baseDir, jobId) {
+  const jobs = loadJobs(baseDir);
+  const idx = jobs.findIndex(j => j.id === jobId);
+  if (idx < 0) return false;
+  jobs.splice(idx, 1);
+  saveJobs(baseDir, jobs);
+  return true;
+}
+
+/**
+ * Pausa un job.
+ * @param {string} baseDir
+ * @param {string} jobId
+ * @returns {boolean}
+ */
+function pauseJob(baseDir, jobId) {
+  const jobs = loadJobs(baseDir);
+  const job = jobs.find(j => j.id === jobId);
+  if (!job) return false;
+  job.status = 'paused';
+  saveJobs(baseDir, jobs);
+  return true;
+}
+
+/**
+ * Reanuda un job pausado.
+ * @param {string} baseDir
+ * @param {string} jobId
+ * @returns {boolean}
+ */
+function resumeJob(baseDir, jobId) {
+  const jobs = loadJobs(baseDir);
+  const job = jobs.find(j => j.id === jobId);
+  if (!job) return false;
+  job.status = 'scheduled';
+  if (!job.nextRun) job.nextRun = computeNextRun(job);
+  saveJobs(baseDir, jobs);
+  return true;
+}
+
+/**
+ * Marca un job como ejecutado y calcula su próxima ejecución.
+ * @param {string} baseDir
+ * @param {string} jobId
+ * @param {object} [result={}] - Resultado de la ejecución.
+ */
+function markExecuted(baseDir, jobId, result = {}) {
+  const jobs = loadJobs(baseDir);
+  const job = jobs.find(j => j.id === jobId);
+  if (!job) return;
+
+  job.lastRunAt = new Date().toISOString();
+
+  // Actualizar repeticiones
+  if (job.repeat) {
+    job.repeat.completed = (job.repeat.completed || 0) + 1;
+    if (job.repeat.times !== null && job.repeat.completed >= job.repeat.times) {
+      job.status = 'completed';
+      job.nextRun = null;
+    }
+  }
+
+  // Calcular próxima ejecución si aún está activo
+  if (job.status === 'scheduled') {
+    job.nextRun = computeNextRun(job);
+  }
+
+  saveJobs(baseDir, jobs);
+
+  // Registrar en log
+  _appendLog(baseDir, {
+    jobId,
+    jobName: job.name,
+    executedAt: job.lastRunAt,
+    status: result.status || 'completed',
+    output: (result.output || '').substring(0, 1000),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Log de ejecuciones
+// ---------------------------------------------------------------------------
+
+function _appendLog(baseDir, entry) {
+  const p = logPath(baseDir);
+  let log = [];
+  try {
+    if (fs.existsSync(p)) {
+      log = JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+  } catch (e) { /* log malformado — resetear */ }
+
+  log.push(entry);
+
+  // Mantener solo las últimas MAX_LOG_ENTRIES entradas
+  if (log.length > MAX_LOG_ENTRIES) {
+    log = log.slice(-MAX_LOG_ENTRIES);
+  }
+
+  atomicWriteJSON(p, log);
+}
+
+/**
+ * Lee el log de ejecuciones.
+ * @param {string} baseDir
+ * @param {number} [limit=20]
+ * @returns {object[]}
+ */
+function readLog(baseDir, limit = 20) {
+  const p = logPath(baseDir);
+  try {
+    if (!fs.existsSync(p)) return [];
+    const log = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return log.slice(-limit);
+  } catch (_) {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// State per agent (portado de rowboat agent-schedule/state-repo.ts)
+// ---------------------------------------------------------------------------
+
+/**
+ * Carga el estado histórico de un agente cron.
+ * Rastrea: lastRunAt, consecutiveErrors, runCount, lastError.
+ *
+ * @param {string} baseDir
+ * @param {string} jobId
+ * @returns {{ lastRunAt: string|null, consecutiveErrors: number, runCount: number, lastError: string|null, lastStatus: string|null }}
+ */
+function getAgentState(baseDir, jobId) {
+  const p = agentStatePath(baseDir);
+  const DEFAULT = { lastRunAt: null, consecutiveErrors: 0, runCount: 0, lastError: null, lastStatus: null };
+  try {
+    if (!fs.existsSync(p)) return { ...DEFAULT };
+    const all = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return all[jobId] ? { ...DEFAULT, ...all[jobId] } : { ...DEFAULT };
+  } catch (_) {
+    return { ...DEFAULT };
+  }
+}
+
+/**
+ * Actualiza el estado de un agente cron tras una ejecución.
+ *
+ * @param {string} baseDir
+ * @param {string} jobId
+ * @param {{ status: 'completed'|'failed'|'skipped', error?: string }} result
+ */
+function updateAgentState(baseDir, jobId, result) {
+  const p = agentStatePath(baseDir);
+  let all = {};
+  try {
+    if (fs.existsSync(p)) all = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (e) { /* agent-state malformado — resetear */ }
+
+  const prev = all[jobId] || { lastRunAt: null, consecutiveErrors: 0, runCount: 0, lastError: null, lastStatus: null };
+
+  all[jobId] = {
+    lastRunAt:         new Date().toISOString(),
+    runCount:          (prev.runCount || 0) + 1,
+    lastStatus:        result.status,
+    lastError:         result.status === 'failed' ? (result.error || 'unknown error') : null,
+    consecutiveErrors: result.status === 'failed'
+      ? (prev.consecutiveErrors || 0) + 1
+      : 0, // reset en éxito
+  };
+
+  atomicWriteJSON(p, all);
+}
+
+/**
+ * Lee el historial resumido de todos los agentes cron.
+ * Útil para diagnóstico: ver qué jobs tienen errores consecutivos.
+ *
+ * @param {string} baseDir
+ * @returns {Array<{ jobId: string, jobName: string, state: object }>}
+ */
+function getAllAgentStates(baseDir) {
+  const p = agentStatePath(baseDir);
+  try {
+    if (!fs.existsSync(p)) return [];
+    const all = JSON.parse(fs.readFileSync(p, 'utf8'));
+    const jobs = loadJobs(baseDir);
+    return Object.entries(all).map(([jobId, state]) => {
+      const job = jobs.find(j => j.id === jobId);
+      return { jobId, jobName: job?.name || jobId, state };
+    });
+  } catch (_) {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  loadJobs,
+  saveJobs,
+  addJob,
+  removeJob,
+  pauseJob,
+  resumeJob,
+  markExecuted,
+  readLog,
+  getAgentState,
+  updateAgentState,
+  getAllAgentStates,
+  CRON_DIR,
+};