@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/audit-tools/canary-monitor.js

@@ -1,352 +1,352 @@
-// Adaptado de temp/ultraship-main/tools/canary-monitor.mjs bajo MIT License
-// Fuente: Houseofmvps/ultraship (https://github.com/Houseofmvps/ultraship)
-'use strict';
-
-const https = require('https');
-const http  = require('http');
-const { writeFileSync, readFileSync, mkdirSync, existsSync } = require('fs');
-const { join, dirname, resolve } = require('path');
-const { validateUrl, createResponseAccumulator } = require('../../hooks/lib/security-net');
-const { outputJSON, outputError } = require('./lib/output');
-
-/** Tiempo de espera máximo por solicitud en milisegundos. */
-const REQUEST_TIMEOUT_MS = 10_000;
-
-/** Encabezados de seguridad que se verifican en las respuestas. */
-const SECURITY_HEADERS = [
-  'x-content-type-options',
-  'x-frame-options',
-  'strict-transport-security',
-  'content-security-policy',
-];
-
-/**
- * Patrones de texto que indican un error real en el cuerpo de la respuesta.
- * @type {RegExp[]}
- */
-const ERROR_PATTERNS = [
-  /Internal Server Error/i,
-  /502 Bad Gateway/i,
-  /503 Service Unavailable/i,
-  /Application Error/i,
-  /Unhandled Exception/i,
-  /Stack Trace/i,
-  /Fatal error/i,
-];
-
-/**
- * Realiza una solicitud HTTP/HTTPS y devuelve métricas sobre la respuesta.
- * Valida la URL antes de realizar cualquier solicitud.
- *
- * @param {string} url
- * @returns {Promise<object>} Resultado con statusCode, latencyMs, bodySize, errores y encabezados de seguridad.
- */
-function checkUrl(url) {
-  // Validar la URL antes de cualquier solicitud (SSRF protection)
-  const validation = validateUrl(url);
-  if (!validation.valid) {
-    return Promise.resolve({
-      url,
-      success:        false,
-      error:          validation.reason,
-      statusCode:     null,
-      latencyMs:      0,
-      bodySize:       0,
-      securityHeaders: [],
-      missingSecurityHeaders: [],
-      issues:         [{ severity: 'critical', message: `URL bloqueada: ${validation.reason}` }],
-    });
-  }
-
-  return new Promise((resolve) => {
-    const parsedUrl = validation.url;
-    const transport = parsedUrl.protocol === 'https:' ? https : http;
-    const accumulator = createResponseAccumulator();
-    const start = Date.now();
-    const issues = [];
-
-    const options = {
-      hostname: parsedUrl.hostname,
-      port:     parsedUrl.port || (parsedUrl.protocol === 'https:' ? 443 : 80),
-      path:     parsedUrl.pathname + (parsedUrl.search || ''),
-      method:   'GET',
-      headers:  { 'User-Agent': 'swl-ses-canary/1.0' },
-      timeout:  REQUEST_TIMEOUT_MS,
-    };
-
-    const req = transport.request(options, (res) => {
-      res.on('data', (chunk) => accumulator.onData(chunk));
-
-      res.on('end', () => {
-        const latencyMs = Date.now() - start;
-        const body      = accumulator.getBody();
-        const bodySize  = accumulator.getTotalSize();
-
-        // Verificar latencia elevada
-        if (latencyMs > 5_000) {
-          issues.push({ severity: 'high', message: `Latencia elevada: ${latencyMs}ms (umbral: 5000ms)` });
-        } else if (latencyMs > 2_000) {
-          issues.push({ severity: 'medium', message: `Latencia moderada: ${latencyMs}ms` });
-        }
-
-        // Verificar código de estado
-        if (res.statusCode >= 500) {
-          issues.push({ severity: 'critical', message: `Error del servidor: HTTP ${res.statusCode}` });
-        } else if (res.statusCode === 404) {
-          issues.push({ severity: 'high', message: 'Recurso no encontrado: HTTP 404' });
-        } else if (res.statusCode >= 400) {
-          issues.push({ severity: 'medium', message: `Error del cliente: HTTP ${res.statusCode}` });
-        }
-
-        // Verificar cuerpo vacío en respuestas exitosas
-        if (res.statusCode >= 200 && res.statusCode < 300 && bodySize === 0) {
-          issues.push({ severity: 'low', message: 'Cuerpo de respuesta vacío en respuesta exitosa' });
-        }
-
-        // Verificar patrones de error en el cuerpo
-        for (const pattern of ERROR_PATTERNS) {
-          if (pattern.test(body)) {
-            issues.push({ severity: 'high', message: `Patrón de error detectado en cuerpo: ${pattern.toString()}` });
-          }
-        }
-
-        // Verificar encabezados de seguridad
-        const presentHeaders  = [];
-        const missingHeaders  = [];
-        for (const header of SECURITY_HEADERS) {
-          if (res.headers[header]) {
-            presentHeaders.push(header);
-          } else {
-            missingHeaders.push(header);
-          }
-        }
-        if (missingHeaders.length > 0) {
-          issues.push({
-            severity: 'low',
-            message:  `Encabezados de seguridad ausentes: ${missingHeaders.join(', ')}`,
-          });
-        }
-
-        resolve({
-          url,
-          success:               res.statusCode >= 200 && res.statusCode < 400,
-          statusCode:            res.statusCode,
-          latencyMs,
-          bodySize,
-          securityHeaders:       presentHeaders,
-          missingSecurityHeaders: missingHeaders,
-          issues,
-          error:                 null,
-          truncated:             accumulator.isTruncated(),
-        });
-      });
-    });
-
-    req.on('timeout', () => {
-      req.destroy();
-      resolve({
-        url,
-        success:               false,
-        error:                 `Tiempo de espera agotado (${REQUEST_TIMEOUT_MS}ms)`,
-        statusCode:            null,
-        latencyMs:             REQUEST_TIMEOUT_MS,
-        bodySize:              0,
-        securityHeaders:       [],
-        missingSecurityHeaders: SECURITY_HEADERS.slice(),
-        issues:                [{ severity: 'critical', message: `Tiempo de espera agotado (${REQUEST_TIMEOUT_MS}ms)` }],
-        truncated:             false,
-      });
-    });
-
-    req.on('error', (err) => {
-      resolve({
-        url,
-        success:               false,
-        error:                 err.message,
-        statusCode:            null,
-        latencyMs:             Date.now() - start,
-        bodySize:              0,
-        securityHeaders:       [],
-        missingSecurityHeaders: SECURITY_HEADERS.slice(),
-        issues:                [{ severity: 'critical', message: `Error de conexión: ${err.message}` }],
-        truncated:             false,
-      });
-    });
-
-    req.end();
-  });
-}
-
-/**
- * Carga el baseline de un archivo JSON.
- * @param {string} baselinePath
- * @returns {object|null}
- */
-function loadBaseline(baselinePath) {
-  if (!existsSync(baselinePath)) return null;
-  try {
-    return JSON.parse(readFileSync(baselinePath, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Compara un resultado actual con el baseline guardado y detecta regresiones.
- * @param {object} current  - Resultado de checkUrl actual.
- * @param {object} baseline - Baseline guardado previamente.
- * @returns {object[]} Lista de regresiones detectadas.
- */
-function compareWithBaseline(current, baseline) {
-  if (!baseline) return [];
-  const regressions = [];
-
-  // Regresión de latencia: >50% más lento
-  if (baseline.latencyMs > 0 && current.latencyMs > baseline.latencyMs * 1.5) {
-    regressions.push({
-      severity: 'high',
-      message:  `Latencia ${current.latencyMs}ms vs baseline ${baseline.latencyMs}ms (+${Math.round((current.latencyMs / baseline.latencyMs - 1) * 100)}%)`,
-    });
-  }
-
-  // Cambio de código de estado
-  if (baseline.statusCode !== null && current.statusCode !== baseline.statusCode) {
-    regressions.push({
-      severity: 'high',
-      message:  `Código de estado cambió de ${baseline.statusCode} a ${current.statusCode}`,
-    });
-  }
-
-  // Aparición de nuevos errores
-  const baselineIssueCount = baseline.issues ? baseline.issues.length : 0;
-  const currentIssueCount  = current.issues ? current.issues.length : 0;
-  if (currentIssueCount > baselineIssueCount) {
-    regressions.push({
-      severity: 'medium',
-      message:  `Nuevos problemas detectados: ${currentIssueCount - baselineIssueCount} (antes ${baselineIssueCount}, ahora ${currentIssueCount})`,
-    });
-  }
-
-  // Caída de tamaño de cuerpo >80%
-  if (baseline.bodySize > 0 && current.bodySize < baseline.bodySize * 0.2) {
-    regressions.push({
-      severity: 'high',
-      message:  `Caída de tamaño de cuerpo >80%: ${current.bodySize}B vs baseline ${baseline.bodySize}B`,
-    });
-  }
-
-  return regressions;
-}
-
-/**
- * Guarda el baseline en un archivo JSON.
- * @param {string} baselinePath
- * @param {object} result
- */
-function saveBaseline(baselinePath, result) {
-  try {
-    const dir = dirname(baselinePath);
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-    writeFileSync(baselinePath, JSON.stringify(result, null, 2), { encoding: 'utf8', mode: 0o600 });
-  } catch (err) {
-    outputError('Error al guardar baseline', { message: err.message });
-  }
-}
-
-/**
- * Ejecuta N verificaciones canary sobre una URL con un intervalo entre cada una.
- * @param {string} url
- * @param {number} checks       - Número de verificaciones a realizar.
- * @param {number} intervalMs   - Milisegundos entre verificaciones.
- * @param {string} baselinePath - Ruta del baseline.
- * @returns {Promise<object>} Resultado agregado.
- */
-function runCanaryChecks(url, checks, intervalMs, baselinePath) {
-  return new Promise((resolve) => {
-    const results = [];
-    let completed = 0;
-
-    function runNext() {
-      checkUrl(url).then((result) => {
-        results.push(result);
-        completed++;
-
-        if (completed >= checks) {
-          // Agregar resultados
-          const successful   = results.filter(r => r.success).length;
-          const avgLatency   = results.reduce((s, r) => s + r.latencyMs, 0) / results.length;
-          const allIssues    = results.flatMap(r => r.issues || []);
-          const lastResult   = results[results.length - 1];
-
-          // Cargar baseline y detectar regresiones
-          const baseline     = loadBaseline(baselinePath);
-          const regressions  = compareWithBaseline(lastResult, baseline);
-
-          // Guardar nuevo baseline si el resultado es saludable
-          if (lastResult.success && lastResult.issues.length === 0) {
-            saveBaseline(baselinePath, lastResult);
-          }
-
-          resolve({
-            url,
-            checks_run:       completed,
-            successful,
-            failed:           completed - successful,
-            avg_latency_ms:   Math.round(avgLatency),
-            min_latency_ms:   Math.min(...results.map(r => r.latencyMs)),
-            max_latency_ms:   Math.max(...results.map(r => r.latencyMs)),
-            last_status_code: lastResult.statusCode,
-            security_headers: lastResult.securityHeaders,
-            missing_security_headers: lastResult.missingSecurityHeaders,
-            issues:           allIssues,
-            regressions,
-            baseline_path:    baselinePath,
-          });
-        } else {
-          // Esperar antes de la siguiente verificación
-          setTimeout(runNext, intervalMs);
-        }
-      });
-    }
-
-    runNext();
-  });
-}
-
-function main() {
-  const args        = process.argv.slice(2);
-  const rawUrl      = args.find(a => !a.startsWith('--'));
-  const checksArg   = args.find(a => a.startsWith('--checks='));
-  const intervalArg = args.find(a => a.startsWith('--interval='));
-  const baselineArg = args.find(a => a.startsWith('--baseline='));
-
-  if (!rawUrl) {
-    outputError('URL requerida. Uso: node canary-monitor.js <url> [--checks=N] [--interval=Ms] [--baseline=ruta]');
-    process.exit(0);
-  }
-
-  // Validar URL antes de cualquier operación
-  const validation = validateUrl(rawUrl);
-  if (!validation.valid) {
-    outputError(`URL bloqueada — no se ejecutará el monitoreo: ${validation.reason}`);
-    process.exit(0);
-  }
-
-  const checks       = checksArg   ? parseInt(checksArg.split('=')[1],   10) : 1;
-  const intervalMs   = intervalArg ? parseInt(intervalArg.split('=')[1], 10) : 5_000;
-  const baselinePath = baselineArg
-    ? resolve(baselineArg.split('=')[1])
-    : join(process.cwd(), '.planning', 'canary', 'baseline.json');
-
-  runCanaryChecks(rawUrl, checks, intervalMs, baselinePath)
-    .then((result) => outputJSON({ success: true, ...result }))
-    .catch((err) => {
-      outputError('Error inesperado en canary-monitor', { message: err.message });
-    });
-}
-
-if (require.main === module) {
-  main();
-}
-
-module.exports = { checkUrl, loadBaseline, compareWithBaseline, runCanaryChecks };
+// Adaptado de temp/ultraship-main/tools/canary-monitor.mjs bajo MIT License
+// Fuente: Houseofmvps/ultraship (https://github.com/Houseofmvps/ultraship)
+'use strict';
+
+const https = require('https');
+const http  = require('http');
+const { writeFileSync, readFileSync, mkdirSync, existsSync } = require('fs');
+const { join, dirname, resolve } = require('path');
+const { validateUrl, createResponseAccumulator } = require('../../hooks/lib/security-net');
+const { outputJSON, outputError } = require('./lib/output');
+
+/** Tiempo de espera máximo por solicitud en milisegundos. */
+const REQUEST_TIMEOUT_MS = 10_000;
+
+/** Encabezados de seguridad que se verifican en las respuestas. */
+const SECURITY_HEADERS = [
+  'x-content-type-options',
+  'x-frame-options',
+  'strict-transport-security',
+  'content-security-policy',
+];
+
+/**
+ * Patrones de texto que indican un error real en el cuerpo de la respuesta.
+ * @type {RegExp[]}
+ */
+const ERROR_PATTERNS = [
+  /Internal Server Error/i,
+  /502 Bad Gateway/i,
+  /503 Service Unavailable/i,
+  /Application Error/i,
+  /Unhandled Exception/i,
+  /Stack Trace/i,
+  /Fatal error/i,
+];
+
+/**
+ * Realiza una solicitud HTTP/HTTPS y devuelve métricas sobre la respuesta.
+ * Valida la URL antes de realizar cualquier solicitud.
+ *
+ * @param {string} url
+ * @returns {Promise<object>} Resultado con statusCode, latencyMs, bodySize, errores y encabezados de seguridad.
+ */
+function checkUrl(url) {
+  // Validar la URL antes de cualquier solicitud (SSRF protection)
+  const validation = validateUrl(url);
+  if (!validation.valid) {
+    return Promise.resolve({
+      url,
+      success:        false,
+      error:          validation.reason,
+      statusCode:     null,
+      latencyMs:      0,
+      bodySize:       0,
+      securityHeaders: [],
+      missingSecurityHeaders: [],
+      issues:         [{ severity: 'critical', message: `URL bloqueada: ${validation.reason}` }],
+    });
+  }
+
+  return new Promise((resolve) => {
+    const parsedUrl = validation.url;
+    const transport = parsedUrl.protocol === 'https:' ? https : http;
+    const accumulator = createResponseAccumulator();
+    const start = Date.now();
+    const issues = [];
+
+    const options = {
+      hostname: parsedUrl.hostname,
+      port:     parsedUrl.port || (parsedUrl.protocol === 'https:' ? 443 : 80),
+      path:     parsedUrl.pathname + (parsedUrl.search || ''),
+      method:   'GET',
+      headers:  { 'User-Agent': 'swl-ses-canary/1.0' },
+      timeout:  REQUEST_TIMEOUT_MS,
+    };
+
+    const req = transport.request(options, (res) => {
+      res.on('data', (chunk) => accumulator.onData(chunk));
+
+      res.on('end', () => {
+        const latencyMs = Date.now() - start;
+        const body      = accumulator.getBody();
+        const bodySize  = accumulator.getTotalSize();
+
+        // Verificar latencia elevada
+        if (latencyMs > 5_000) {
+          issues.push({ severity: 'high', message: `Latencia elevada: ${latencyMs}ms (umbral: 5000ms)` });
+        } else if (latencyMs > 2_000) {
+          issues.push({ severity: 'medium', message: `Latencia moderada: ${latencyMs}ms` });
+        }
+
+        // Verificar código de estado
+        if (res.statusCode >= 500) {
+          issues.push({ severity: 'critical', message: `Error del servidor: HTTP ${res.statusCode}` });
+        } else if (res.statusCode === 404) {
+          issues.push({ severity: 'high', message: 'Recurso no encontrado: HTTP 404' });
+        } else if (res.statusCode >= 400) {
+          issues.push({ severity: 'medium', message: `Error del cliente: HTTP ${res.statusCode}` });
+        }
+
+        // Verificar cuerpo vacío en respuestas exitosas
+        if (res.statusCode >= 200 && res.statusCode < 300 && bodySize === 0) {
+          issues.push({ severity: 'low', message: 'Cuerpo de respuesta vacío en respuesta exitosa' });
+        }
+
+        // Verificar patrones de error en el cuerpo
+        for (const pattern of ERROR_PATTERNS) {
+          if (pattern.test(body)) {
+            issues.push({ severity: 'high', message: `Patrón de error detectado en cuerpo: ${pattern.toString()}` });
+          }
+        }
+
+        // Verificar encabezados de seguridad
+        const presentHeaders  = [];
+        const missingHeaders  = [];
+        for (const header of SECURITY_HEADERS) {
+          if (res.headers[header]) {
+            presentHeaders.push(header);
+          } else {
+            missingHeaders.push(header);
+          }
+        }
+        if (missingHeaders.length > 0) {
+          issues.push({
+            severity: 'low',
+            message:  `Encabezados de seguridad ausentes: ${missingHeaders.join(', ')}`,
+          });
+        }
+
+        resolve({
+          url,
+          success:               res.statusCode >= 200 && res.statusCode < 400,
+          statusCode:            res.statusCode,
+          latencyMs,
+          bodySize,
+          securityHeaders:       presentHeaders,
+          missingSecurityHeaders: missingHeaders,
+          issues,
+          error:                 null,
+          truncated:             accumulator.isTruncated(),
+        });
+      });
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      resolve({
+        url,
+        success:               false,
+        error:                 `Tiempo de espera agotado (${REQUEST_TIMEOUT_MS}ms)`,
+        statusCode:            null,
+        latencyMs:             REQUEST_TIMEOUT_MS,
+        bodySize:              0,
+        securityHeaders:       [],
+        missingSecurityHeaders: SECURITY_HEADERS.slice(),
+        issues:                [{ severity: 'critical', message: `Tiempo de espera agotado (${REQUEST_TIMEOUT_MS}ms)` }],
+        truncated:             false,
+      });
+    });
+
+    req.on('error', (err) => {
+      resolve({
+        url,
+        success:               false,
+        error:                 err.message,
+        statusCode:            null,
+        latencyMs:             Date.now() - start,
+        bodySize:              0,
+        securityHeaders:       [],
+        missingSecurityHeaders: SECURITY_HEADERS.slice(),
+        issues:                [{ severity: 'critical', message: `Error de conexión: ${err.message}` }],
+        truncated:             false,
+      });
+    });
+
+    req.end();
+  });
+}
+
+/**
+ * Carga el baseline de un archivo JSON.
+ * @param {string} baselinePath
+ * @returns {object|null}
+ */
+function loadBaseline(baselinePath) {
+  if (!existsSync(baselinePath)) return null;
+  try {
+    return JSON.parse(readFileSync(baselinePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compara un resultado actual con el baseline guardado y detecta regresiones.
+ * @param {object} current  - Resultado de checkUrl actual.
+ * @param {object} baseline - Baseline guardado previamente.
+ * @returns {object[]} Lista de regresiones detectadas.
+ */
+function compareWithBaseline(current, baseline) {
+  if (!baseline) return [];
+  const regressions = [];
+
+  // Regresión de latencia: >50% más lento
+  if (baseline.latencyMs > 0 && current.latencyMs > baseline.latencyMs * 1.5) {
+    regressions.push({
+      severity: 'high',
+      message:  `Latencia ${current.latencyMs}ms vs baseline ${baseline.latencyMs}ms (+${Math.round((current.latencyMs / baseline.latencyMs - 1) * 100)}%)`,
+    });
+  }
+
+  // Cambio de código de estado
+  if (baseline.statusCode !== null && current.statusCode !== baseline.statusCode) {
+    regressions.push({
+      severity: 'high',
+      message:  `Código de estado cambió de ${baseline.statusCode} a ${current.statusCode}`,
+    });
+  }
+
+  // Aparición de nuevos errores
+  const baselineIssueCount = baseline.issues ? baseline.issues.length : 0;
+  const currentIssueCount  = current.issues ? current.issues.length : 0;
+  if (currentIssueCount > baselineIssueCount) {
+    regressions.push({
+      severity: 'medium',
+      message:  `Nuevos problemas detectados: ${currentIssueCount - baselineIssueCount} (antes ${baselineIssueCount}, ahora ${currentIssueCount})`,
+    });
+  }
+
+  // Caída de tamaño de cuerpo >80%
+  if (baseline.bodySize > 0 && current.bodySize < baseline.bodySize * 0.2) {
+    regressions.push({
+      severity: 'high',
+      message:  `Caída de tamaño de cuerpo >80%: ${current.bodySize}B vs baseline ${baseline.bodySize}B`,
+    });
+  }
+
+  return regressions;
+}
+
+/**
+ * Guarda el baseline en un archivo JSON.
+ * @param {string} baselinePath
+ * @param {object} result
+ */
+function saveBaseline(baselinePath, result) {
+  try {
+    const dir = dirname(baselinePath);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(baselinePath, JSON.stringify(result, null, 2), { encoding: 'utf8', mode: 0o600 });
+  } catch (err) {
+    outputError('Error al guardar baseline', { message: err.message });
+  }
+}
+
+/**
+ * Ejecuta N verificaciones canary sobre una URL con un intervalo entre cada una.
+ * @param {string} url
+ * @param {number} checks       - Número de verificaciones a realizar.
+ * @param {number} intervalMs   - Milisegundos entre verificaciones.
+ * @param {string} baselinePath - Ruta del baseline.
+ * @returns {Promise<object>} Resultado agregado.
+ */
+function runCanaryChecks(url, checks, intervalMs, baselinePath) {
+  return new Promise((resolve) => {
+    const results = [];
+    let completed = 0;
+
+    function runNext() {
+      checkUrl(url).then((result) => {
+        results.push(result);
+        completed++;
+
+        if (completed >= checks) {
+          // Agregar resultados
+          const successful   = results.filter(r => r.success).length;
+          const avgLatency   = results.reduce((s, r) => s + r.latencyMs, 0) / results.length;
+          const allIssues    = results.flatMap(r => r.issues || []);
+          const lastResult   = results[results.length - 1];
+
+          // Cargar baseline y detectar regresiones
+          const baseline     = loadBaseline(baselinePath);
+          const regressions  = compareWithBaseline(lastResult, baseline);
+
+          // Guardar nuevo baseline si el resultado es saludable
+          if (lastResult.success && lastResult.issues.length === 0) {
+            saveBaseline(baselinePath, lastResult);
+          }
+
+          resolve({
+            url,
+            checks_run:       completed,
+            successful,
+            failed:           completed - successful,
+            avg_latency_ms:   Math.round(avgLatency),
+            min_latency_ms:   Math.min(...results.map(r => r.latencyMs)),
+            max_latency_ms:   Math.max(...results.map(r => r.latencyMs)),
+            last_status_code: lastResult.statusCode,
+            security_headers: lastResult.securityHeaders,
+            missing_security_headers: lastResult.missingSecurityHeaders,
+            issues:           allIssues,
+            regressions,
+            baseline_path:    baselinePath,
+          });
+        } else {
+          // Esperar antes de la siguiente verificación
+          setTimeout(runNext, intervalMs);
+        }
+      });
+    }
+
+    runNext();
+  });
+}
+
+function main() {
+  const args        = process.argv.slice(2);
+  const rawUrl      = args.find(a => !a.startsWith('--'));
+  const checksArg   = args.find(a => a.startsWith('--checks='));
+  const intervalArg = args.find(a => a.startsWith('--interval='));
+  const baselineArg = args.find(a => a.startsWith('--baseline='));
+
+  if (!rawUrl) {
+    outputError('URL requerida. Uso: node canary-monitor.js <url> [--checks=N] [--interval=Ms] [--baseline=ruta]');
+    process.exit(0);
+  }
+
+  // Validar URL antes de cualquier operación
+  const validation = validateUrl(rawUrl);
+  if (!validation.valid) {
+    outputError(`URL bloqueada — no se ejecutará el monitoreo: ${validation.reason}`);
+    process.exit(0);
+  }
+
+  const checks       = checksArg   ? parseInt(checksArg.split('=')[1],   10) : 1;
+  const intervalMs   = intervalArg ? parseInt(intervalArg.split('=')[1], 10) : 5_000;
+  const baselinePath = baselineArg
+    ? resolve(baselineArg.split('=')[1])
+    : join(process.cwd(), '.planning', 'canary', 'baseline.json');
+
+  runCanaryChecks(rawUrl, checks, intervalMs, baselinePath)
+    .then((result) => outputJSON({ success: true, ...result }))
+    .catch((err) => {
+      outputError('Error inesperado en canary-monitor', { message: err.message });
+    });
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { checkUrl, loadBaseline, compareWithBaseline, runCanaryChecks };