abworks-dev/readme-banner

¿Qué hace readme-banner?

Genera banners SVG de dos temas con la CLI local; solo edita el README cuando el usuario solicita explícitamente insertar o actualizar el banner. La configuración y las restricciones específicas se encuentran en la referencia de configuración. No inventes indicadores de CLI ni campos de configuración de memoria.

Confirmar el alcance de la operación

1. Determina la ruta absoluta del repositorio de destino. El repositorio del proyecto del usuario puede ser diferente del directorio fuente de la herramienta readme-banner. Lee el directorio de trabajo actual y verifica el README / metadatos del proyecto de destino; el directorio donde se encuentra el skill, el checkout de la herramienta y el directorio predeterminado del terminal no son automáticamente el destino.
2. Si hay ambigüedad sobre el destino, primero pregunta al usuario; no añadas un banner a la propia herramienta solo porque el directorio actual sea readme-banner. Solo genera configuración e imágenes en el repositorio de la herramienta si el usuario lo selecciona explícitamente como destino.
3. Determina si se trata de "solo generar recursos / fragmento de vista previa" o "insertar / actualizar un README específico". Sin una solicitud explícita de edición del README, nunca pases --readme ni edites el README a través de otras herramientas de edición de archivos. Confirma el nombre del archivo; no modifiques automáticamente todas las versiones de idioma ni todos los README en todos los directorios.
4. Verifica la configuración existente, imágenes, bloques gestionados y cambios no confirmados relacionados. Conserva las modificaciones no relacionadas; no hagas reset, clean, elimines recursos antiguos ni reemplaces otra documentación del usuario. Si ya hay configuración, léela y reutilízala; sobrescribir requiere confirmación adicional, no uses --force por costumbre.

Elegir la apariencia

• preset: usa primero ascii; es el primer renderizador, no el nombre de "todos los temas".
• theme: elige independientemente: terminal (verde terminal), ocean (azul cian), neon (morado rosa), minimal (monocromático). Respeta las preferencias del usuario; si no se especifica, sugiere brevemente uno según el carácter del proyecto, no inventes IDs de temas personalizados.
• Obtén título, subtítulo y arte incorporado opcional. Evita usar logotipos de marca no solicitados; donut es un ejemplo no comercial. Las piezas incorporadas que dependen del reloj en tiempo real serán rechazadas para que el resultado sea reproducible; no eludas esta verificación.
• El título ASCII tiene un máximo de 120 caracteres y debe ser compatible con la fuente incorporada seleccionada; los caracteres chinos, emojis y puntuación no soportada no se eliminan silenciosamente. Si se necesita un título corto alternativo en inglés, pide confirmación al usuario; el texto original se puede colocar en una tagline de texto plano de hasta 240 caracteres.
• mixed conserva las mayúsculas y minúsculas del inglés; otras fuentes se convierten a mayúsculas. El límite de 20/60 caracteres de la URL ascendente no se aplica a la CLI local, pero 120 caracteres no es una garantía de estética. Los títulos largos deben acortarse, o considerar slim o reducir el arte.
• Para títulos animados, usa glint o type; si el usuario quiere un banner estático, usa still. still también congela el arte incorporado; el SVG aún conserva los datos de los fotogramas de animación del arte, por lo que no garantiza una reducción significativa del tamaño del archivo.

Usar un punto de entrada CLI fiable

Requiere Node.js >=22; verifica primero la versión disponible.

Si ya tienes un checkout del código fuente de la herramienta

Si el entorno de la tarea ya tiene el código fuente de esta herramienta, úsalo directamente; no descargues desde Internet la misma herramienta:

1. Ejecuta npm install en el directorio del código fuente de la herramienta; prepare compilará TypeScript. No instales dependencias en el proyecto de destino del usuario solo para construir la herramienta.
2. Verifica el punto de entrada local:

node "/ruta/absoluta/readme-banner/bin/readme-banner.mjs" --help

3. Mantén el punto de entrada local de Node para el resto de la ejecución; pasa siempre explícitamente el --cwd de destino. Incluso si el directorio de trabajo del comando es el checkout de la herramienta, no omitas el aislamiento del destino.

Si no tienes un checkout local

Puedes usar el punto de entrada de la etiqueta Git fija v0.1.0 del repositorio público abworks-dev/readme-banner; esto requiere Git, conexión de red y permiso del usuario para instalar/ejecutar código de terceros de confianza:

npx --yes --package github:abworks-dev/readme-banner#v0.1.0 readme-banner --help

@readme-banner/cli es solo un nombre de paquete local aún no publicado en npm; no uses npx @readme-banner/cli ni inventes otros paquetes npm. Si la instalación falla, informa del error real; no recurras a fuentes desconocidas, versiones desconocidas recientes ni servicios SVG remotos.

Si aparece EALLOWGIT, no modifiques automáticamente la configuración global de npm. Solo si el usuario ya ha autorizado la instalación/ejecución de este repositorio de confianza y las políticas de la organización lo permiten, se puede usar en un npm que soporte la opción: npx --allow-git=root --yes --package github:abworks-dev/readme-banner#v0.1.0 readme-banner …. Si no hay autorización, pregunta primero; si las políticas de la organización lo restringen, detente. Si la versión antigua de npm no reconoce la opción, usa el comando normal o instala desde el código fuente autorizado.

El siguiente ejemplo usa el punto de entrada local; para el punto de entrada remoto, reemplaza todo el prefijo node … por el comando npx --yes --package … readme-banner completo anterior, sin cambiar la semántica de los argumentos posteriores.

Flujo de ejecución: init → generate → check

1. Crear o reutilizar configuración

node "/ruta/absoluta/readme-banner/bin/readme-banner.mjs" init --cwd "/ruta/absoluta/proyecto-destino" --config "banner.config.json" --preset ascii --theme ocean --title "MI PROYECTO" --tagline "Construye algo útil" --art donut --effect glint

• init solo crea la configuración, no genera imágenes ni modifica el README; a continuación debes ejecutar generate.
• Si ya hay configuración, léela primero y luego modifícala mínimamente según la intención del usuario, o reutilízala directamente; no uses --force automáticamente para recrearla. Omite los parámetros de subtítulo o arte si no se necesitan.
• La fuente, color, sombra, posición, velocidad, fondo, etc., se configuran a través de los campos compatibles del JSON. Lee primero la referencia de configuración; no inventes opciones como init --font.
• La configuración solo puede ser JSON; no crees configuraciones que ejecuten código, no instales complementos de configuración arbitrarios, no obtengas ni inyectes SVG remotos proporcionados por el usuario.

2. Generar recursos (modo predeterminado)

node "/ruta/absoluta/readme-banner/bin/readme-banner.mjs" generate --cwd "/ruta/absoluta/proyecto-destino" --config "banner.config.json"

Por defecto, escribe banner.light.svg y banner.dark.svg en el outputDir configurado, y genera un fragmento <picture>. Este comando no debe modificar el README. Si el usuario solo solicita recursos, detente aquí; no insertes el fragmento en el README a escondidas.

3. Insertar solo con autorización de edición del README

node "/ruta/absoluta/readme-banner/bin/readme-banner.mjs" generate --cwd "/ruta/absoluta/proyecto-destino" --config "banner.config.json" --readme "README.md"

--readme solo puede especificar un archivo .md existente. La CLI mantiene el bloque entre <!-- readme-banner:start --> y <!-- readme-banner:end -->. Verifica que el contenido fuera del bloque permanezca sin cambios; en el mismo README, incluso si el marcado completo aparece dentro de un bloque de código de ejemplo, se tratará de forma conservadora como un marcado duplicado, así que no insertes pares de marcado de demostración adicionales. Si hay anomalías en el marcado, investiga el error; no elimines texto no relacionado ni amplíes el rango de reemplazo. Usa el fragmento generado real: las URL deben ser relativas al README de destino, codificadas por segmentos URI, el texto alternativo debe escaparse con HTML; no combines HTML sin escapar por tu cuenta.

4. Verificar los resultados

# Tareas sin autorización para editar el README: solo verificar imágenes
node "/ruta/absoluta/readme-banner/bin/readme-banner.mjs" generate --cwd "/ruta/absoluta/proyecto-destino" --config "banner.config.json" --check

# Tareas que ya involucran explícitamente un README específico: verificar también el bloque gestionado
node "/ruta/absoluta/readme-banner/bin/readme-banner.mjs" generate --cwd "/ruta/absoluta/proyecto-destino" --config "banner.config.json" --readme "README.md" --check

• --check no escribe archivos; los recursos faltantes o desactualizados deben fallar. En caso de fallo, informa la razón; no ignores el código de salida ni afirmes que una verificación no ejecutada pasó.
• Verifica que ambos SVG existan y que la ruta sea correcta; si hay una herramienta de visualización, verifica el efecto real del tema claro/oscuro, título largo y arte. No puedes asumir que la generación exitosa del SVG implica que todos los clientes Markdown reproducirán la animación.
• Para resultados legibles por máquina, usa generate --json; los metadatos disponibles se pueden consultar con presets --json y themes --json.
• Si se reportan errores de protección contra rutas fuera de límites, enlaces simbólicos o enlaces físicos, confirma el destino del usuario y elige un archivo normal seguro dentro del directorio raíz; los archivos existentes con nlink > 1 (número de enlaces físicos) serán rechazados. No desactives la protección ni muevas el archivo fuera de la raíz para "evitarla".

Seguridad de comandos y archivos

• Todas las ejecuciones deben establecer explícitamente el directorio de trabajo correcto y pasar el --cwd de destino; no confíes en el directorio predeterminado del entorno del agente.
• Los títulos, rutas y subtítulos son parámetros de datos. Prioriza el uso de una API de ejecución que acepte una matriz de parámetros; si usas shell, cita/escapa cada parámetro según las reglas de ese shell. Las comillas dobles del ejemplo solo son válidas para valores de marcador de posición simples dentro de ellas; no protegen contra todas las interpolaciones de shell; no concatenes datos no confiables en comandos, eval o scripts sin escapar. Las rutas de Windows también deben citarse individualmente.
• Solo modifica la configuración autorizada por el usuario, los recursos generados y el bloque gestionado especificado; no modifiques código de negocio, documentación no relacionada ni cambios existentes del usuario.
• No hagas commit, push, crees repositorios remotos, publiques releases, subas imágenes, publiques paquetes npm ni desencadenes ninguna otra publicación remota automáticamente. Todo esto requiere una solicitud explícita independiente.

Informe de entrega

Informa brevemente: repositorio de destino, preset/theme/título utilizado, las dos imágenes generadas, si se modificó el README y su ubicación, y los resultados reales de las comprobaciones ejecutadas. Sin autorización para el README, indica claramente "No se modificó el README" y puedes devolver el fragmento generado para que el usuario decida. Enumera las sustituciones de glifos que aún requieren confirmación del usuario, títulos demasiado largos o problemas de compatibilidad con el visor; no afirmes que pruebas no ejecutadas han pasado.