@saulwade/swl-ses 2.3.0 → 2.4.1

package/hooks/lib/deep-links.js

@@ -1,185 +1,185 @@
-'use strict';
-
-/**
- * Deep Links — Helper zero-deps para construir URLs que abren archivos en
- * IDEs y editores directamente desde notificaciones.
- *
- * Cubre VS Code (vscode://), VS Code Insiders, Cursor (cursor://), JetBrains
- * (jetbrains://), Codex Desktop (codex://) y fallbacks para apps sin esquema
- * oficial (Visual Studio en Windows usa CLI fallback).
- *
- * Documentación funcional y matriz de soporte en:
- *   habilidades/agent-deep-links/SKILL.md
- *
- * Documentado en ADR-0029 (integración parcial awesome-codex-skills).
- *
- * @module hooks/lib/deep-links
- */
-
-const path = require('node:path');
-
-/**
- * IDEs soportados con esquema oficial confiable.
- * Cualquier valor fuera de esta lista retorna null en construirDeepLink.
- */
-const IDES_SOPORTADOS = Object.freeze([
-  'vscode',
-  'vscode-insiders',
-  'cursor',
-  'codex',
-  'jetbrains-idea',
-  'jetbrains-pycharm',
-  'jetbrains-webstorm',
-  'jetbrains-goland',
-  'jetbrains-rubymine',
-  'jetbrains-clion',
-  'jetbrains-rider',
-  'jetbrains-phpstorm',
-]);
-
-/**
- * Map de IDE → esquema base. JetBrains usa formato distinto (manejado en
- * función separada).
- */
-const ESQUEMAS = Object.freeze({
-  'vscode':           'vscode://file',
-  'vscode-insiders':  'vscode-insiders://file',
-  'cursor':           'cursor://file',
-});
-
-/**
- * Indica si un IDE soporta deep links a archivo:línea.
- *
- * @param {string} ide - Identificador del IDE.
- * @returns {boolean}
- */
-function soportaDeepLinks(ide) {
-  if (typeof ide !== 'string') return false;
-  return IDES_SOPORTADOS.includes(ide);
-}
-
-/**
- * Normaliza un path absoluto para uso en deep links.
- * - Resuelve a absoluto (rechaza relativos).
- * - Normaliza separadores (Windows backslash → forward slash; VS Code/Cursor
- *   aceptan forward slashes incluso en Windows).
- * - Encoding URI para espacios y caracteres especiales.
- *
- * @param {string} rutaAbsoluta
- * @returns {string|null}
- * @private
- */
-function _normalizarPath(rutaAbsoluta) {
-  if (typeof rutaAbsoluta !== 'string' || rutaAbsoluta.length === 0) {
-    return null;
-  }
-  if (!path.isAbsolute(rutaAbsoluta)) {
-    return null;
-  }
-  // path.resolve normaliza .., ., dobles separadores.
-  const resuelto = path.resolve(rutaAbsoluta);
-  // Forward slashes en todos los SO — los IDEs los aceptan en Windows también.
-  const forwardSlashes = resuelto.split(path.sep).join('/');
-  // encodeURI preserva : y / (los necesitamos), encodea espacios y caracteres especiales.
-  return encodeURI(forwardSlashes);
-}
-
-/**
- * Valida que línea y columna sean enteros positivos si están definidos.
- * @private
- */
-function _validarPosicion(linea, columna) {
-  if (linea !== undefined && linea !== null) {
-    if (!Number.isInteger(linea) || linea < 1) return false;
-  }
-  if (columna !== undefined && columna !== null) {
-    if (!Number.isInteger(columna) || columna < 1) return false;
-  }
-  return true;
-}
-
-/**
- * Construye un deep link para abrir un archivo en el IDE especificado.
- *
- * Retorna null cuando:
- *   - El IDE no soporta deep links a archivos (Codex Desktop, Xcode, etc.).
- *   - La ruta no es absoluta o está vacía.
- *   - Línea/columna están definidas pero no son enteros positivos.
- *   - El IDE es JetBrains pero falta `proyecto` (requerido).
- *
- * @param {object} params
- * @param {string} params.ide - 'vscode' | 'vscode-insiders' | 'cursor' | 'jetbrains-<ide-id>'
- * @param {string} params.rutaAbsoluta - Path absoluto al archivo. Forward o backslashes.
- * @param {number} [params.linea] - Línea 1-indexed.
- * @param {number} [params.columna] - Columna 1-indexed.
- * @param {string} [params.proyecto] - Solo para JetBrains: nombre del proyecto.
- * @returns {string|null} URL del deep link, o null si no se puede construir.
- */
-function construirDeepLink(params) {
-  const { ide, rutaAbsoluta, linea, columna, proyecto } = params || {};
-
-  if (!soportaDeepLinks(ide)) return null;
-  if (!_validarPosicion(linea, columna)) return null;
-
-  const pathNormalizado = _normalizarPath(rutaAbsoluta);
-  if (!pathNormalizado) return null;
-
-  // JetBrains usa un formato distinto al resto.
-  if (ide.startsWith('jetbrains-')) {
-    if (!proyecto || typeof proyecto !== 'string') return null;
-    const ideId = ide.slice('jetbrains-'.length);
-    // jetbrains://idea/navigate/reference?project=<name>&path=<rel>:<line>
-    const query = new URLSearchParams({
-      project: proyecto,
-      path: linea ? `${pathNormalizado}:${linea}` : pathNormalizado,
-    }).toString();
-    return `jetbrains://${ideId}/navigate/reference?${query}`;
-  }
-
-  // VS Code / Cursor / VS Code Insiders.
-  const base = ESQUEMAS[ide];
-  let url = `${base}${pathNormalizado.startsWith('/') ? '' : '/'}${pathNormalizado}`;
-  if (linea) {
-    url += `:${linea}`;
-    if (columna) {
-      url += `:${columna}`;
-    }
-  }
-  return url;
-}
-
-/**
- * Formato según receptor — envuelve un deep link en la sintaxis correcta del
- * canal destino. Devuelve texto plano (con sufijo "(abrir manualmente)") si
- * el deep link es null.
- *
- * @param {string|null} deepLink - URL del deep link, o null para fallback.
- * @param {string} etiqueta - Texto visible para el usuario.
- * @param {string} receptor - 'telegram' | 'discord' | 'slack' | 'email' | 'plain'
- * @returns {string}
- */
-function formatearEnlace(deepLink, etiqueta, receptor) {
-  if (!deepLink) {
-    return `${etiqueta} (abrir manualmente)`;
-  }
-  switch (receptor) {
-    case 'slack':
-      return `<${deepLink}|${etiqueta}>`;
-    case 'telegram':
-    case 'discord':
-      // Ambos usan Markdown estándar para enlaces.
-      return `[${etiqueta}](${deepLink})`;
-    case 'email':
-      return `<a href="${deepLink}">${etiqueta}</a>`;
-    case 'plain':
-    default:
-      return `${etiqueta}: ${deepLink}`;
-  }
-}
-
-module.exports = {
-  construirDeepLink,
-  formatearEnlace,
-  soportaDeepLinks,
-  IDES_SOPORTADOS,
-};
+'use strict';
+
+/**
+ * Deep Links — Helper zero-deps para construir URLs que abren archivos en
+ * IDEs y editores directamente desde notificaciones.
+ *
+ * Cubre VS Code (vscode://), VS Code Insiders, Cursor (cursor://), JetBrains
+ * (jetbrains://), Codex Desktop (codex://) y fallbacks para apps sin esquema
+ * oficial (Visual Studio en Windows usa CLI fallback).
+ *
+ * Documentación funcional y matriz de soporte en:
+ *   habilidades/agent-deep-links/SKILL.md
+ *
+ * Documentado en ADR-0029 (integración parcial awesome-codex-skills).
+ *
+ * @module hooks/lib/deep-links
+ */
+
+const path = require('node:path');
+
+/**
+ * IDEs soportados con esquema oficial confiable.
+ * Cualquier valor fuera de esta lista retorna null en construirDeepLink.
+ */
+const IDES_SOPORTADOS = Object.freeze([
+  'vscode',
+  'vscode-insiders',
+  'cursor',
+  'codex',
+  'jetbrains-idea',
+  'jetbrains-pycharm',
+  'jetbrains-webstorm',
+  'jetbrains-goland',
+  'jetbrains-rubymine',
+  'jetbrains-clion',
+  'jetbrains-rider',
+  'jetbrains-phpstorm',
+]);
+
+/**
+ * Map de IDE → esquema base. JetBrains usa formato distinto (manejado en
+ * función separada).
+ */
+const ESQUEMAS = Object.freeze({
+  'vscode':           'vscode://file',
+  'vscode-insiders':  'vscode-insiders://file',
+  'cursor':           'cursor://file',
+});
+
+/**
+ * Indica si un IDE soporta deep links a archivo:línea.
+ *
+ * @param {string} ide - Identificador del IDE.
+ * @returns {boolean}
+ */
+function soportaDeepLinks(ide) {
+  if (typeof ide !== 'string') return false;
+  return IDES_SOPORTADOS.includes(ide);
+}
+
+/**
+ * Normaliza un path absoluto para uso en deep links.
+ * - Resuelve a absoluto (rechaza relativos).
+ * - Normaliza separadores (Windows backslash → forward slash; VS Code/Cursor
+ *   aceptan forward slashes incluso en Windows).
+ * - Encoding URI para espacios y caracteres especiales.
+ *
+ * @param {string} rutaAbsoluta
+ * @returns {string|null}
+ * @private
+ */
+function _normalizarPath(rutaAbsoluta) {
+  if (typeof rutaAbsoluta !== 'string' || rutaAbsoluta.length === 0) {
+    return null;
+  }
+  if (!path.isAbsolute(rutaAbsoluta)) {
+    return null;
+  }
+  // path.resolve normaliza .., ., dobles separadores.
+  const resuelto = path.resolve(rutaAbsoluta);
+  // Forward slashes en todos los SO — los IDEs los aceptan en Windows también.
+  const forwardSlashes = resuelto.split(path.sep).join('/');
+  // encodeURI preserva : y / (los necesitamos), encodea espacios y caracteres especiales.
+  return encodeURI(forwardSlashes);
+}
+
+/**
+ * Valida que línea y columna sean enteros positivos si están definidos.
+ * @private
+ */
+function _validarPosicion(linea, columna) {
+  if (linea !== undefined && linea !== null) {
+    if (!Number.isInteger(linea) || linea < 1) return false;
+  }
+  if (columna !== undefined && columna !== null) {
+    if (!Number.isInteger(columna) || columna < 1) return false;
+  }
+  return true;
+}
+
+/**
+ * Construye un deep link para abrir un archivo en el IDE especificado.
+ *
+ * Retorna null cuando:
+ *   - El IDE no soporta deep links a archivos (Codex Desktop, Xcode, etc.).
+ *   - La ruta no es absoluta o está vacía.
+ *   - Línea/columna están definidas pero no son enteros positivos.
+ *   - El IDE es JetBrains pero falta `proyecto` (requerido).
+ *
+ * @param {object} params
+ * @param {string} params.ide - 'vscode' | 'vscode-insiders' | 'cursor' | 'jetbrains-<ide-id>'
+ * @param {string} params.rutaAbsoluta - Path absoluto al archivo. Forward o backslashes.
+ * @param {number} [params.linea] - Línea 1-indexed.
+ * @param {number} [params.columna] - Columna 1-indexed.
+ * @param {string} [params.proyecto] - Solo para JetBrains: nombre del proyecto.
+ * @returns {string|null} URL del deep link, o null si no se puede construir.
+ */
+function construirDeepLink(params) {
+  const { ide, rutaAbsoluta, linea, columna, proyecto } = params || {};
+
+  if (!soportaDeepLinks(ide)) return null;
+  if (!_validarPosicion(linea, columna)) return null;
+
+  const pathNormalizado = _normalizarPath(rutaAbsoluta);
+  if (!pathNormalizado) return null;
+
+  // JetBrains usa un formato distinto al resto.
+  if (ide.startsWith('jetbrains-')) {
+    if (!proyecto || typeof proyecto !== 'string') return null;
+    const ideId = ide.slice('jetbrains-'.length);
+    // jetbrains://idea/navigate/reference?project=<name>&path=<rel>:<line>
+    const query = new URLSearchParams({
+      project: proyecto,
+      path: linea ? `${pathNormalizado}:${linea}` : pathNormalizado,
+    }).toString();
+    return `jetbrains://${ideId}/navigate/reference?${query}`;
+  }
+
+  // VS Code / Cursor / VS Code Insiders.
+  const base = ESQUEMAS[ide];
+  let url = `${base}${pathNormalizado.startsWith('/') ? '' : '/'}${pathNormalizado}`;
+  if (linea) {
+    url += `:${linea}`;
+    if (columna) {
+      url += `:${columna}`;
+    }
+  }
+  return url;
+}
+
+/**
+ * Formato según receptor — envuelve un deep link en la sintaxis correcta del
+ * canal destino. Devuelve texto plano (con sufijo "(abrir manualmente)") si
+ * el deep link es null.
+ *
+ * @param {string|null} deepLink - URL del deep link, o null para fallback.
+ * @param {string} etiqueta - Texto visible para el usuario.
+ * @param {string} receptor - 'telegram' | 'discord' | 'slack' | 'email' | 'plain'
+ * @returns {string}
+ */
+function formatearEnlace(deepLink, etiqueta, receptor) {
+  if (!deepLink) {
+    return `${etiqueta} (abrir manualmente)`;
+  }
+  switch (receptor) {
+    case 'slack':
+      return `<${deepLink}|${etiqueta}>`;
+    case 'telegram':
+    case 'discord':
+      // Ambos usan Markdown estándar para enlaces.
+      return `[${etiqueta}](${deepLink})`;
+    case 'email':
+      return `<a href="${deepLink}">${etiqueta}</a>`;
+    case 'plain':
+    default:
+      return `${etiqueta}: ${deepLink}`;
+  }
+}
+
+module.exports = {
+  construirDeepLink,
+  formatearEnlace,
+  soportaDeepLinks,
+  IDES_SOPORTADOS,
+};