@samline/notify 0.1.1 → 0.1.6

package/.local/agent-index.md

@@ -0,0 +1,63 @@
+# Agent Index
+
+## Instrucción Para La IA
+
+Este es el índice interno que la IA debe leer después de pasar por AGENTS.md en la raíz del repositorio.
+
+La función de este archivo es actuar como índice maestro de los documentos internos en .local y orientar qué archivos revisar según el tipo de tarea.
+
+## Regla Principal
+
+Antes de comenzar cualquier tarea en este repositorio, la IA debe leer este archivo y usarlo para decidir qué otros documentos internos necesita revisar.
+
+La memoria de sesión del chat no debe considerarse la fuente única de verdad para reglas, pendientes, lecciones o preferencias del proyecto. Si la IA guarda algo relevante allí, también debe llevarlo al documento persistente correspondiente dentro de .local.
+
+## Nota Sobre AGENTS.md
+
+AGENTS.md en la raíz funciona como bootstrap local para dirigir a la IA hacia este índice interno.
+
+Ese archivo no debe versionarse ni subirse al repositorio. Debe tratarse como una instrucción local de arranque para la IA.
+
+## Índice De Archivos Internos
+
+### Siempre revisar según el contexto
+
+1. package-replication-guide.md
+   Usar cuando se vaya a replicar este scaffold para otro paquete o producto similar.
+
+2. deploy-and-release-guide.md
+   Usar cuando la tarea implique versionado, release, deploy, publicación npm, tags o GitHub Actions de publicación.
+
+3. todo.md
+   Usar para revisar tareas pendientes, mejoras futuras, bugs por corregir y trabajo que el usuario dejó explícitamente pendiente.
+
+4. lessons.md
+   Usar para revisar errores, correcciones, sugerencias y preferencias del usuario que la IA no debe olvidar ni repetir.
+
+## Orden Recomendado De Lectura
+
+### Si la tarea es general
+
+1. agent-index.md
+2. todo.md
+3. lessons.md
+
+### Si la tarea es crear un paquete o scaffold nuevo
+
+1. agent-index.md
+2. package-replication-guide.md
+3. todo.md
+4. lessons.md
+
+### Si la tarea es publicar o hacer release
+
+1. agent-index.md
+2. deploy-and-release-guide.md
+3. todo.md
+4. lessons.md
+
+## Alcance Actual
+
+Por ahora este archivo solo funciona como índice de entrada para la IA.
+
+En el futuro puede ampliarse con más instrucciones operativas, prioridades, reglas de lectura o flujos especializados.

package/.local/deploy-and-release-guide.md

@@ -0,0 +1,277 @@
+# Guía Interna De Release, Deploy Y Tags Para La IA
+
+## Instrucción Para La IA
+
+Este archivo existe para que la IA pueda revisar el proceso correcto de versionado, release, publicación y tags antes de intentar desplegar una nueva versión del paquete.
+
+Cuando una conversación pida publicar, desplegar, versionar o empujar un tag, la IA debe leer este documento y validar que el flujo propuesto coincide con el estado real del repositorio.
+
+## Objetivo
+
+Definir un playbook operativo para:
+
+1. revisar si los cambios corresponden a major, minor o patch
+2. actualizar la versión del paquete con criterio semver
+3. preparar el release
+4. empujar el commit y el tag correctos
+5. disparar el workflow de publicación del repositorio
+
+## Recomendación Previa Obligatoria
+
+Antes de automatizar releases desde GitHub, se recomienda tener ya configurado en GitHub el secreto NPM_TOKEN.
+
+Este repositorio ya tiene un workflow de publicación que depende de ese secreto. Si NPM_TOKEN no existe o no tiene permisos válidos, el tag se puede empujar correctamente pero la publicación en npm fallará.
+
+## Nota Sobre npm publish --provenance
+
+No usar `npm publish --provenance` en este repositorio a menos que primero se configure correctamente trusted publishing entre GitHub Actions y npm.
+
+Contexto operativo:
+
+1. el workflow llegó a validar tag, instalación, build, typecheck, tests y credenciales npm
+2. aun así, el paso `Publish to npm` falló usando `--provenance`
+3. el publish volvió a funcionar al cambiar el workflow a `npm publish`
+
+Regla práctica:
+
+1. mientras este repositorio dependa de `NPM_TOKEN`, usar `npm publish`
+2. solo reintroducir `--provenance` si también se configura y verifica trusted publishing end-to-end
+3. si se vuelve a intentar, validar primero en una release real o en documentación oficial actual de npm y GitHub Actions
+
+## Flujo Real Del Repositorio
+
+El workflow actual publica en npm cuando se hace push de un tag con formato v\*.
+
+Resumen del flujo real:
+
+1. se activa con push de tags tipo v1.2.3
+2. valida que el tag coincida exactamente con la versión en package.json
+3. ejecuta npm ci
+4. ejecuta build
+5. ejecuta typecheck
+6. ejecuta tests
+7. comprueba si esa versión ya existe en npm
+8. publica con npm publish --provenance usando NPM_TOKEN solo si la versión todavía no existe
+
+## Regla Inicial Antes De Versionar
+
+La IA no debe subir una nueva versión sin revisar primero el tipo de cambio.
+
+Primero debe clasificar los cambios en una de estas categorías:
+
+### Patch
+
+Usar patch cuando hay:
+
+- correcciones de bugs sin romper compatibilidad
+- mejoras internas sin cambios en la API pública
+- documentación o ajustes pequeños si también van acompañados de una corrección publicada
+- fixes de build o testing que no cambian el contrato público
+
+Ejemplo:
+
+- 0.5.0 -> 0.5.1
+
+### Minor
+
+Usar minor cuando hay:
+
+- nuevas funciones compatibles hacia atrás
+- nuevos exports o nuevos helpers sin romper la API actual
+- soporte adicional para otro entorno o framework sin cambiar contratos existentes
+- mejoras relevantes del producto manteniendo compatibilidad
+
+Ejemplo:
+
+- 0.5.0 -> 0.6.0
+
+### Major
+
+Usar major cuando hay:
+
+- cambios incompatibles con la API actual
+- eliminación o renombre de funciones públicas
+- cambios de comportamiento que puedan romper consumidores existentes
+- cambios de runtime mínimo o de estrategia de imports que obliguen migración
+
+Ejemplo:
+
+- 0.5.0 -> 1.0.0
+
+## Checklist De Evaluación Semver
+
+Antes de decidir la nueva versión, la IA debe responder:
+
+1. ¿La API pública cambió de forma incompatible?
+2. ¿Se eliminó o renombró algún export?
+3. ¿Se añadió funcionalidad nueva sin romper compatibilidad?
+4. ¿Solo se corrigieron bugs o detalles internos?
+5. ¿Cambió la versión mínima de Node o alguna dependencia crítica?
+6. ¿Cambió el comportamiento por defecto de una función pública?
+7. ¿La documentación describe una nueva capacidad o una ruptura?
+
+Regla práctica:
+
+1. Si hay ruptura, major.
+2. Si no hay ruptura pero sí nueva capacidad, minor.
+3. Si solo hay corrección o ajuste compatible, patch.
+
+## Secuencia Recomendada De Release
+
+### Paso 1: revisar el estado del repositorio
+
+La IA debe comprobar:
+
+1. rama actual
+2. cambios sin commit
+3. si el branch está alineado con origin
+4. si hay tags locales o remotos pendientes de considerar
+
+### Paso 2: revisar el alcance del cambio
+
+La IA debe leer el diff o el resumen de cambios y clasificar el release como major, minor o patch.
+
+No debe saltar directamente a npm version sin esa revisión.
+
+### Paso 3: validar que el repositorio está listo
+
+Antes de versionar, comprobar:
+
+1. npm run build
+2. npm run typecheck
+3. npm test
+
+Si alguno falla, no se debe crear versión ni tag.
+
+### Paso 4: actualizar la versión
+
+Usar una de estas rutas según el caso:
+
+```bash
+npm version patch
+npm version minor
+npm version major
+```
+
+Si se requiere controlar el mensaje de commit o separar pasos, la IA puede actualizar package.json manualmente y crear el tag después, pero el camino simple recomendado es usar npm version.
+
+### Paso 5: verificar la versión resultante
+
+Después de cambiar la versión, confirmar:
+
+1. package.json actualizado
+2. commit de versionado creado, si aplica
+3. tag local creado con formato vX.Y.Z
+
+### Paso 6: empujar commit y tag
+
+Flujo recomendado:
+
+```bash
+git push origin main
+git push origin vX.Y.Z
+```
+
+También puede usarse:
+
+```bash
+git push origin main --follow-tags
+```
+
+si el tag ya quedó asociado al commit local correcto.
+
+### Paso 7: verificar publicación
+
+Una vez empujado el tag, la IA debe confirmar:
+
+1. que GitHub Actions se disparó
+2. que el workflow validó el tag contra package.json
+3. que build, typecheck y tests pasaron
+4. que npm publish terminó sin error
+
+## Relación Entre Tag Y package.json
+
+Este repositorio tiene una validación explícita: el tag debe coincidir exactamente con la versión en package.json.
+
+Ejemplo válido:
+
+- package.json version: 0.5.1
+- tag: v0.5.1
+
+Ejemplos inválidos:
+
+- package.json version: 0.5.1 y tag: v0.5.2
+- package.json version: 0.5.1 y tag: 0.5.1
+
+Si no coinciden, el workflow falla antes de publicar.
+
+## Casos En Los Que No Debe Hacerse Release
+
+La IA no debe crear versión nueva si ocurre alguno de estos casos:
+
+1. solo hay cambios locales sin commit y no se pidió release real
+2. el tipo de cambio todavía no está claro
+3. build, typecheck o tests fallan
+4. package.json no está alineado con el release propuesto
+5. no existe NPM_TOKEN válido en GitHub y el objetivo es publicar automáticamente
+6. el repositorio local no está en el commit correcto para etiquetar
+
+## Comportamiento Cuando La Versión Ya Existe
+
+Si la versión del tag ya fue publicada manualmente en npm antes de que corra GitHub Actions, el workflow no debe fallar por intentar republicarla.
+
+Debe:
+
+1. validar igualmente que tag y package.json coincidan
+2. ejecutar npm ci, build, typecheck y tests
+3. detectar que la versión ya existe en npm
+4. omitir el paso de npm publish sin marcar error
+
+Esto evita falsos negativos en releases donde la publicación manual y el tag ocurrieron en momentos distintos.
+
+## Recomendación Para Controlar Mejor El Historial
+
+Antes de cada release, la IA debería revisar si los cambios del periodo ameritan major, minor o patch para mantener un historial semántico confiable.
+
+No conviene tratar todas las publicaciones como patch por costumbre. Eso degrada el valor del versionado y complica la expectativa del consumidor.
+
+## Comandos De Referencia
+
+### Revisar estado
+
+```bash
+git status --short --branch
+git log --oneline --decorate -5
+git tag --sort=-version:refname | head
+```
+
+### Validar proyecto antes de release
+
+```bash
+npm run build
+npm run typecheck
+npm test
+```
+
+### Versionar y publicar por tag
+
+```bash
+npm version patch
+git push origin main
+git push origin vX.Y.Z
+```
+
+Reemplazar patch por minor o major cuando corresponda.
+
+## Regla Operativa Final Para La IA
+
+Si una conversación futura pide publicar una nueva versión, la IA debe:
+
+1. revisar este documento
+2. clasificar el release como major, minor o patch
+3. verificar build, typecheck y tests
+4. confirmar que package.json y el tag coinciden
+5. empujar commit y tag
+6. asumir que la publicación depende del workflow y del secreto NPM_TOKEN en GitHub
+
+No debe tratar release, tag y deploy como un solo paso ciego.

package/.local/lessons.md

@@ -0,0 +1,76 @@
+# Lessons
+
+## Instrucción Para La IA
+
+Este archivo guarda lecciones operativas del proyecto para evitar repetir errores y para mantener presentes las recomendaciones del usuario durante futuras tareas.
+
+La IA debe revisarlo antes de ejecutar trabajo importante y actualizarlo cuando el usuario marque un comportamiento como incorrecto, mejorable o deseable.
+
+## Qué Debe Guardarse Aquí
+
+1. errores de la IA que el usuario indique como tales
+2. comportamientos que no deben repetirse
+3. preferencias explícitas del usuario
+4. recomendaciones prácticas para futuras sesiones
+5. aclaraciones sobre cómo interpretar instrucciones del proyecto
+
+## Regla De Uso
+
+Solo deben registrarse lecciones confirmadas por el usuario o aprendidas con claridad durante el trabajo en este proyecto.
+
+No deben agregarse opiniones vagas ni reglas inventadas.
+
+Si la IA guarda en memoria de sesión una lección, preferencia o corrección operativa que deba sobrevivir a la sesión, también debe escribirla aquí para mantener la continuidad del proyecto.
+
+## Lecciones Actuales
+
+### Persistencia de contexto operativo
+
+- lección: la memoria de sesión del chat puede perderse y no debe ser la única ubicación para información operativa importante.
+- implicación: si una nota de sesión corresponde a un pendiente, lección, regla interna o preferencia persistente, la IA debe duplicarla en el archivo adecuado de .local.
+
+### Documentos internos para la IA
+
+- lección: los archivos dentro de .local son instrucciones internas para la IA, no documentación pública del paquete.
+- implicación: la IA debe tratarlos como notas de operación y referencia antes de actuar.
+
+### AGENTS.md local
+
+- lección: AGENTS.md en la raíz debe funcionar como instrucción local para la IA, pero no debe subirse al repositorio.
+- implicación: la IA debe mantener AGENTS.md fuera de Git y no asumir que es un archivo destinado a versionarse.
+
+### Honestidad sobre el estado de implementación
+
+- lección: no afirmar que un cambio quedó escrito si no fue persistido realmente en el workspace.
+- implicación: la IA debe reportar con precisión lo que sí quedó aplicado y lo que sigue pendiente.
+
+### Pendientes explícitos
+
+- lección: las tareas futuras deben quedar en todo.md solo si el usuario dijo explícitamente que quedan pendientes.
+- implicación: la IA no debe promover ideas implícitas a backlog sin confirmación.
+
+### Documentación pública en inglés
+
+- lección: la documentación pública del paquete debe escribirse en inglés.
+- implicación: README y docs/ no deben mezclar español en futuras iteraciones.
+
+
+### Versiones del CDN en releases
+
+- lección: cuando se cambia la versión publicada del paquete, también deben actualizarse las URLs versionadas del CDN en la documentación pública.
+- implicación: antes de crear commit, tag o release, la IA debe revisar README y docs para confirmar que las referencias usan la misma versión que package.json.
+
+### Pre-task reading enforcement
+
+- lección: la IA debe leer `.local/agent-index.md` antes de comenzar cualquier tarea en el repositorio.
+- implicación: si la IA inicia trabajo sin haber leído `agent-index.md`, debe reconocer el error, corregirlo, y anotar la lección en este archivo para evitar repetirla.
+
+Ejemplo de corrección aplicada: la IA inició la implementación inicial del paquete sin leer `agent-index.md` primero; al detectarlo, leyó `agent-index.md`, actualizó `.local/lessons.md` con esta lección y continuará aplicando la regla en tareas futuras.
+
+## Cómo Añadir Nuevas Lecciones
+
+Usar bloques simples con:
+
+- situación
+- error o preferencia detectada
+- regla a mantener en adelante