@saulwade/swl-ses 2.6.0 → 2.8.0

package/habilidades/agent-deep-links/SKILL.md

@@ -1,148 +1,148 @@
----
-name: agent-deep-links
-description: >
-  Constructor y validador de deep links para abrir archivos, líneas, carpetas y
-  ajustes directamente en IDEs y editores desde notificaciones, mensajes del
-  gateway o output de agentes. Cubre VS Code (vscode://), VS Code Insiders,
-  Cursor (cursor://), JetBrains (jetbrains://), Codex Desktop (codex://) y
-  fallbacks para apps sin esquema oficial. Cargar cuando un agente o hook deba
-  emitir referencias a archivo:línea que el usuario pueda abrir con un clic
-  desde Telegram, desktop notifications, Discord, Slack o e-mail.
-version: 1.0.0
-nivelRiesgo: BAJO
-herramientasPermitidas: [Read]
-exclusiones:
-  - "No invocar para generar URLs HTTP/HTTPS de navegación web — esto es solo para deep links a apps de escritorio."
-  - "No invocar para integraciones con servicios externos (Linear, Notion, Jira); este skill solo cubre IDEs y editores locales del desarrollador."
-  - "No invocar para enlaces a sesiones de Claude Code en la nube — esos son URLs claude.ai/code/..., no deep links."
----
-
-# /habilidades/agent-deep-links — Deep links a IDEs
-
-## Cuándo cargar
-
-- Antes de emitir una notificación que incluya referencias a archivos del proyecto
-  desde `notificador-swl`, `hooks/lib/gateway-notify.js`, `inbox-aviso.js`,
-  `notificacion-sesion-stop.js` o cualquier hook que mencione `archivo:línea`.
-- Al diseñar nuevos hooks o agentes que produzcan output con referencias a código
-  que el usuario pueda querer abrir directamente.
-- Antes de generar mensajes desde el `documentador-swl` cuyo destino sea un canal
-  externo (Telegram, Discord, e-mail) y el receptor probablemente esté en su
-  IDE.
-
-## Cuándo NO cargar
-
-- Cuando la notificación es solo texto plano sin referencias a archivos
-  (mensajes de status, métricas agregadas).
-- Cuando el receptor es un agente, no un humano (los agentes no abren IDEs).
-- Cuando estás generando URLs de navegación web (HTTP/HTTPS) — usa generación
-  estándar.
-- Cuando el proyecto no expone su path absoluto al gateway (los deep links de
-  IDE requieren absolute paths).
-
-## Helper programático
-
-La lógica del skill está implementada en `hooks/lib/deep-links.js`. El skill
-documenta **qué** generar; el helper genera **cómo**. Para uso desde código:
-
-```js
-const { construirDeepLink, soportaDeepLinks } = require('./lib/deep-links');
-
-const url = construirDeepLink({
-  ide:        'cursor',      // 'vscode' | 'vscode-insiders' | 'cursor' | 'codex' | 'jetbrains' | 'visualstudio'
-  rutaAbsoluta: '/abs/path/a/archivo.js',
-  linea:      42,
-  columna:    8,
-});
-// → 'cursor://file//abs/path/a/archivo.js:42:8'
-
-if (!url) {
-  // El IDE solicitado no soporta deep links — usar fallback en texto plano
-}
-```
-
-## Matriz de soporte por IDE
-
-| IDE / App | Esquema | Soporte | Patrón canónico | Notas |
-|---|---|---|---|---|
-| **VS Code** | `vscode://` | Total | `vscode://file/<absoluteFile>:<line>:<column>` | Requiere VS Code instalado en máquina del receptor. |
-| **VS Code Insiders** | `vscode-insiders://` | Total | `vscode-insiders://file/<absoluteFile>:<line>:<column>` | Esquema específico Insiders. |
-| **Cursor** | `cursor://` | Total | `cursor://file/<absoluteFile>:<line>:<column>` | Fork de VS Code; misma forma. |
-| **Codex Desktop** | `codex://` | Total | `codex://threads/<thread-uuid>`, `codex://settings` | Para hilos y settings; no archivos. |
-| **JetBrains (IntelliJ/PyCharm/WebStorm/...)** | `jetbrains://` | Total | `jetbrains://<ide-id>/navigate/reference?project=<name>&path=<relPath>` | Requiere nombre del proyecto. Ver fila JetBrains abajo. |
-| **JetBrains Toolbox URL** | `idea://` (deprecado), `jetbrains://idea/...` | Parcial | `jetbrains://idea/navigate/reference?project=<name>&path=<rel>:<line>` | Cada IDE tiene su `<ide-id>`: idea, pycharm, webstorm, goland, rubymine, etc. |
-| **Visual Studio (Windows)** | (no estándar) | Sin esquema oficial | Usar CLI fallback: `devenv /edit <rutaAbsoluta>` | Solo Windows. |
-| **Xcode** | `xcode://` | Parcial | `xcode://...` | Esquema existe; rutas de archivo no bien documentadas. NO confiable. |
-| **Claude Desktop** | `claude://` | Desconocido | `claude://...` | Esquema registrado, rutas no documentadas. |
-| **Codex CLI** (terminal) | n/a | No aplica | n/a | Es CLI; no abre archivos en IDE. Usar fallback texto plano. |
-| **Cualquier app web** | n/a | No aplica | n/a | Si el destino es navegador, usar URL HTTP estándar. |
-
-## Reglas de construcción
-
-1. **Path absoluto obligatorio**. Deep links con rutas relativas no funcionan.
-   El helper rechaza `path.relative` y retorna `null`.
-2. **Encoding de paths con espacios**: aplicar `encodeURI` al path completo (no
-   solo al filename). El helper lo hace automáticamente.
-3. **Línea y columna son opcionales**: si no se especifican, el IDE abre al
-   inicio del archivo. Línea 1, columna 1 es válido pero redundante.
-4. **JetBrains requiere `proyecto`**: sin el nombre del proyecto, el deep link
-   no resuelve. Si no se conoce, usar `vscode://` como fallback (la mayoría de
-   los desarrolladores tienen VS Code instalado).
-5. **NUNCA inventar esquemas**: si la matriz dice "No aplica" o "Desconocido",
-   el helper retorna `null` y el caller debe usar texto plano.
-
-## Formato según receptor
-
-| Receptor | Forma del enlace |
-|---|---|
-| **Telegram** (Markdown V2) | `[abrir en IDE](cursor://file//abs/path:42:8)` |
-| **Discord** | `[abrir en IDE](cursor://file//abs/path:42:8)` |
-| **Slack** | `<cursor://file//abs/path:42:8\|abrir en Cursor>` (pipe-separado) |
-| **Desktop notification** (Linux/macOS) | URL plana sin label; el notificador maneja el clic |
-| **E-mail HTML** | `<a href="cursor://file//abs/path:42:8">abrir en Cursor</a>` |
-| **Texto plano / fallback** | `archivo.js:42 (abrir manualmente)` |
-
-## Gotchas observables
-
-- **El receptor debe tener el IDE instalado**: un enlace `cursor://` no funciona
-  si el receptor no tiene Cursor instalado. NO hay forma de detectarlo desde
-  el emisor; documentar al usuario que el deep link es opt-in.
-- **Slack tiene su propia sintaxis** `<url|label>`, no Markdown estándar. Mezclar
-  los formatos rompe el clic.
-- **Windows usa backslashes**: el path absoluto en Windows es
-  `C:\Users\...\archivo.js`. El esquema `vscode://file/C:\\Users\\...` requiere
-  doble-backslash en algunos casos; el helper normaliza con `path.resolve` +
-  `encodeURI` para producir `vscode://file/C:/Users/...` (slashes forward) que
-  VS Code/Cursor sí aceptan correctamente.
-- **JetBrains URL Handler debe estar habilitado**: en JetBrains está bajo
-  Settings → Tools → Web Browsers and Preview → "Use JetBrains as a
-  redirect..." NO está activado por defecto en todas las distribuciones.
-
-## Integración con SWL
-
-Hoy se integra en `hooks/lib/gateway-notify.js` (opt-in): cuando un caller pasa
-`payload.fileRef = { archivo, linea, columna }` Y existe `payload.idePreferido`,
-el helper enriquece el mensaje con el deep link en el formato del adaptador
-destino (Telegram / Discord / etc.).
-
-Extensiones futuras (no implementadas hoy):
-
-- `notificador-swl` (Telegram nativo): pasar `idePreferido` desde
-  `instintos/perfil-usuario.yaml § ide_preferido`.
-- `documentador-swl`: enlaces a archivos citados en docs generados.
-- `revisor-codigo-swl`: enlaces a archivo:línea en reportes de hallazgos.
-
-## Origen
-
-Adaptado del skill `agent-deep-links` de
-`temp/awesome-codex-skills-master/agent-deep-links/` (ComposioHQ, MIT) con:
-
-- Frontmatter al estándar SWL (es-MX, `nivelRiesgo`, `exclusiones`,
-  `herramientasPermitidas`).
-- Matriz extendida con JetBrains (no estaba) y Visual Studio fallback.
-- Sección "Formato según receptor" agregada para Telegram/Discord además del
-  Slack original.
-- Helper Node.js (`hooks/lib/deep-links.js`) que el repo origen no tenía.
-- Sección "Integración con SWL" agregada.
-
-Documentado en ADR-0029 (integración parcial awesome-codex-skills, Opción B).
+---
+name: agent-deep-links
+description: >
+  Constructor y validador de deep links para abrir archivos, líneas, carpetas y
+  ajustes directamente en IDEs y editores desde notificaciones, mensajes del
+  gateway o output de agentes. Cubre VS Code (vscode://), VS Code Insiders,
+  Cursor (cursor://), JetBrains (jetbrains://), Codex Desktop (codex://) y
+  fallbacks para apps sin esquema oficial. Cargar cuando un agente o hook deba
+  emitir referencias a archivo:línea que el usuario pueda abrir con un clic
+  desde Telegram, desktop notifications, Discord, Slack o e-mail.
+version: 1.0.0
+nivelRiesgo: BAJO
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No invocar para generar URLs HTTP/HTTPS de navegación web — esto es solo para deep links a apps de escritorio."
+  - "No invocar para integraciones con servicios externos (Linear, Notion, Jira); este skill solo cubre IDEs y editores locales del desarrollador."
+  - "No invocar para enlaces a sesiones de Claude Code en la nube — esos son URLs claude.ai/code/..., no deep links."
+---
+
+# /habilidades/agent-deep-links — Deep links a IDEs
+
+## Cuándo cargar
+
+- Antes de emitir una notificación que incluya referencias a archivos del proyecto
+  desde `notificador-swl`, `hooks/lib/gateway-notify.js`, `inbox-aviso.js`,
+  `notificacion-sesion-stop.js` o cualquier hook que mencione `archivo:línea`.
+- Al diseñar nuevos hooks o agentes que produzcan output con referencias a código
+  que el usuario pueda querer abrir directamente.
+- Antes de generar mensajes desde el `documentador-swl` cuyo destino sea un canal
+  externo (Telegram, Discord, e-mail) y el receptor probablemente esté en su
+  IDE.
+
+## Cuándo NO cargar
+
+- Cuando la notificación es solo texto plano sin referencias a archivos
+  (mensajes de status, métricas agregadas).
+- Cuando el receptor es un agente, no un humano (los agentes no abren IDEs).
+- Cuando estás generando URLs de navegación web (HTTP/HTTPS) — usa generación
+  estándar.
+- Cuando el proyecto no expone su path absoluto al gateway (los deep links de
+  IDE requieren absolute paths).
+
+## Helper programático
+
+La lógica del skill está implementada en `hooks/lib/deep-links.js`. El skill
+documenta **qué** generar; el helper genera **cómo**. Para uso desde código:
+
+```js
+const { construirDeepLink, soportaDeepLinks } = require('./lib/deep-links');
+
+const url = construirDeepLink({
+  ide:        'cursor',      // 'vscode' | 'vscode-insiders' | 'cursor' | 'codex' | 'jetbrains' | 'visualstudio'
+  rutaAbsoluta: '/abs/path/a/archivo.js',
+  linea:      42,
+  columna:    8,
+});
+// → 'cursor://file//abs/path/a/archivo.js:42:8'
+
+if (!url) {
+  // El IDE solicitado no soporta deep links — usar fallback en texto plano
+}
+```
+
+## Matriz de soporte por IDE
+
+| IDE / App | Esquema | Soporte | Patrón canónico | Notas |
+|---|---|---|---|---|
+| **VS Code** | `vscode://` | Total | `vscode://file/<absoluteFile>:<line>:<column>` | Requiere VS Code instalado en máquina del receptor. |
+| **VS Code Insiders** | `vscode-insiders://` | Total | `vscode-insiders://file/<absoluteFile>:<line>:<column>` | Esquema específico Insiders. |
+| **Cursor** | `cursor://` | Total | `cursor://file/<absoluteFile>:<line>:<column>` | Fork de VS Code; misma forma. |
+| **Codex Desktop** | `codex://` | Total | `codex://threads/<thread-uuid>`, `codex://settings` | Para hilos y settings; no archivos. |
+| **JetBrains (IntelliJ/PyCharm/WebStorm/...)** | `jetbrains://` | Total | `jetbrains://<ide-id>/navigate/reference?project=<name>&path=<relPath>` | Requiere nombre del proyecto. Ver fila JetBrains abajo. |
+| **JetBrains Toolbox URL** | `idea://` (deprecado), `jetbrains://idea/...` | Parcial | `jetbrains://idea/navigate/reference?project=<name>&path=<rel>:<line>` | Cada IDE tiene su `<ide-id>`: idea, pycharm, webstorm, goland, rubymine, etc. |
+| **Visual Studio (Windows)** | (no estándar) | Sin esquema oficial | Usar CLI fallback: `devenv /edit <rutaAbsoluta>` | Solo Windows. |
+| **Xcode** | `xcode://` | Parcial | `xcode://...` | Esquema existe; rutas de archivo no bien documentadas. NO confiable. |
+| **Claude Desktop** | `claude://` | Desconocido | `claude://...` | Esquema registrado, rutas no documentadas. |
+| **Codex CLI** (terminal) | n/a | No aplica | n/a | Es CLI; no abre archivos en IDE. Usar fallback texto plano. |
+| **Cualquier app web** | n/a | No aplica | n/a | Si el destino es navegador, usar URL HTTP estándar. |
+
+## Reglas de construcción
+
+1. **Path absoluto obligatorio**. Deep links con rutas relativas no funcionan.
+   El helper rechaza `path.relative` y retorna `null`.
+2. **Encoding de paths con espacios**: aplicar `encodeURI` al path completo (no
+   solo al filename). El helper lo hace automáticamente.
+3. **Línea y columna son opcionales**: si no se especifican, el IDE abre al
+   inicio del archivo. Línea 1, columna 1 es válido pero redundante.
+4. **JetBrains requiere `proyecto`**: sin el nombre del proyecto, el deep link
+   no resuelve. Si no se conoce, usar `vscode://` como fallback (la mayoría de
+   los desarrolladores tienen VS Code instalado).
+5. **NUNCA inventar esquemas**: si la matriz dice "No aplica" o "Desconocido",
+   el helper retorna `null` y el caller debe usar texto plano.
+
+## Formato según receptor
+
+| Receptor | Forma del enlace |
+|---|---|
+| **Telegram** (Markdown V2) | `[abrir en IDE](cursor://file//abs/path:42:8)` |
+| **Discord** | `[abrir en IDE](cursor://file//abs/path:42:8)` |
+| **Slack** | `<cursor://file//abs/path:42:8\|abrir en Cursor>` (pipe-separado) |
+| **Desktop notification** (Linux/macOS) | URL plana sin label; el notificador maneja el clic |
+| **E-mail HTML** | `<a href="cursor://file//abs/path:42:8">abrir en Cursor</a>` |
+| **Texto plano / fallback** | `archivo.js:42 (abrir manualmente)` |
+
+## Gotchas observables
+
+- **El receptor debe tener el IDE instalado**: un enlace `cursor://` no funciona
+  si el receptor no tiene Cursor instalado. NO hay forma de detectarlo desde
+  el emisor; documentar al usuario que el deep link es opt-in.
+- **Slack tiene su propia sintaxis** `<url|label>`, no Markdown estándar. Mezclar
+  los formatos rompe el clic.
+- **Windows usa backslashes**: el path absoluto en Windows es
+  `C:\Users\...\archivo.js`. El esquema `vscode://file/C:\\Users\\...` requiere
+  doble-backslash en algunos casos; el helper normaliza con `path.resolve` +
+  `encodeURI` para producir `vscode://file/C:/Users/...` (slashes forward) que
+  VS Code/Cursor sí aceptan correctamente.
+- **JetBrains URL Handler debe estar habilitado**: en JetBrains está bajo
+  Settings → Tools → Web Browsers and Preview → "Use JetBrains as a
+  redirect..." NO está activado por defecto en todas las distribuciones.
+
+## Integración con SWL
+
+Hoy se integra en `hooks/lib/gateway-notify.js` (opt-in): cuando un caller pasa
+`payload.fileRef = { archivo, linea, columna }` Y existe `payload.idePreferido`,
+el helper enriquece el mensaje con el deep link en el formato del adaptador
+destino (Telegram / Discord / etc.).
+
+Extensiones futuras (no implementadas hoy):
+
+- `notificador-swl` (Telegram nativo): pasar `idePreferido` desde
+  `instintos/perfil-usuario.yaml § ide_preferido`.
+- `documentador-swl`: enlaces a archivos citados en docs generados.
+- `revisor-codigo-swl`: enlaces a archivo:línea en reportes de hallazgos.
+
+## Origen
+
+Adaptado del skill `agent-deep-links` de
+`temp/awesome-codex-skills-master/agent-deep-links/` (ComposioHQ, MIT) con:
+
+- Frontmatter al estándar SWL (es-MX, `nivelRiesgo`, `exclusiones`,
+  `herramientasPermitidas`).
+- Matriz extendida con JetBrains (no estaba) y Visual Studio fallback.
+- Sección "Formato según receptor" agregada para Telegram/Discord además del
+  Slack original.
+- Helper Node.js (`hooks/lib/deep-links.js`) que el repo origen no tenía.
+- Sección "Integración con SWL" agregada.
+
+Documentado en ADR-0029 (integración parcial awesome-codex-skills, Opción B).