Libretto

Libretto es un conjunto de herramientas para construir integraciones web robustas. Le proporciona a tu agente de codificación un navegador en vivo y una CLI eficiente en tokens para:

• Inspeccionar páginas en vivo con mínimo overhead de contexto
• Capturar tráfico de red para realizar ingeniería inversa de las API del sitio
• Grabar acciones del usuario y reproducirlas como scripts de automatización
• Depurar flujos de trabajo rotos de forma interactiva contra el sitio real

En Saffron Health construimos Libretto para ayudarnos a mantener nuestras integraciones de navegador con software sanitario común. Lo estamos abriendo en código abierto para que otros equipos tengan una tarea más fácil al hacer lo mismo.

https://github.com/user-attachments/assets/9b9a0ab3-5133-4b20-b3be-459943349d18

Enlaces rápidos

• Sitio web: libretto.sh
• Documentación: libretto.sh/docs
• Repositorio: github.com/saffron-health/libretto
• Discord: discord.gg/NYrG56hVDt

Instalación

# Añade Libretto a tu proyecto. Requiere Node.js y npm.
npm install libretto

# Inicio por primera vez: instalar skills y descargar Chromium
npx libretto setup

# Verificar el estado del espacio de trabajo en cualquier momento
npx libretto status

setup crea el directorio .libretto/, instala las skills del agente y descarga Chromium a menos que pases --skip-browsers.

Casos de uso

Libretto está diseñado para ser usado como una skill a través de tu agente de codificación. Aquí hay algunos ejemplos de prompts:

Generación de scripts de una sola vez

Usa la skill de Libretto. Ve a LinkedIn y extrae los primeros 10 posts: contenido, quién lo publicó, número de reacciones, los primeros 25 comentarios y los primeros 25 republicaciones.

Tu agente de codificación abrirá una ventana para que inicies sesión en LinkedIn y luego comenzará a explorar automáticamente.

Construcción interactiva de scripts

Te voy a mostrar un flujo de trabajo en el EHR de eclinicalworks para obtener el ID del seguro principal de un paciente. Usa la skill de libretto para convertirlo en un script de playwright que tome el nombre del paciente y su fecha de nacimiento como entrada para devolver el ID del seguro. La URL es...

Libretto puede leer las acciones que realizas en el navegador, por lo que puedes ejecutar un flujo de trabajo y luego pedirle que use tus acciones para reconstruirlo.

Convertir automatización de navegador a peticiones de red

Tenemos un script de navegador en ./integration.ts que automatiza ir a Hacker News y obtener los primeros 10 posts. Conviértelo a scripts de red directos. Usa la skill de Libretto.

Libretto puede leer las peticiones de red desde el navegador, lo que puede usar para hacer ingeniería inversa de la API y crear un script que llame directamente a esas peticiones. Hacer llamadas a la API directamente es más rápido y más fiable que la automatización de la interfaz de usuario. También puedes pedirle a Libretto que realice un análisis de seguridad que examine las peticiones en busca de cookies de seguridad comunes, para que puedas entender si un enfoque basado en peticiones de red será seguro.

Reparar integraciones rotas

Tenemos un script de navegador en ./integration.ts que se supone que debe ir a Availity y realizar una verificación de elegibilidad para un paciente. Pero al ejecutarlo obtengo un error de selector roto. Arrégialo. Usa la skill de Libretto.

Los agentes pueden usar Libretto para reproducir el fallo, pausar el flujo de trabajo en cualquier punto, inspeccionar la página en vivo y corregir problemas, todo de forma autónoma.

Uso desde la CLI

También puedes usar Libretto directamente desde la línea de comandos. Todos los comandos aceptan --session <nombre> para apuntar a una sesión específica.

npx libretto open <url>                    # lanzar navegador y abrir una URL
npx libretto run ./integration.ts --headless # ejecutar un flujo de trabajo y cerrar al tener éxito
npx libretto run ./integration.ts --headless --stay-open-on-success # mantener la ejecución exitosa inspeccionable
npx libretto snapshot --session <nombre>     # capturar una captura de pantalla y un árbol de accesibilidad compacto
npx libretto exec "<código>"                # ejecutar Playwright TypeScript contra la página abierta
npx libretto close                          # cerrar el navegador

Las sesiones run son inspeccionables a través de los mismos comandos respaldados por un demonio que las sesiones open. Las ejecuciones exitosas cierran el navegador por defecto; pasa --stay-open-on-success para mantener el navegador abierto para pages, snapshot y exec. Los flujos de trabajo fallidos o pausados mantienen el navegador abierto para que puedas inspeccionar el estado exacto de la página antes de corregir o reanudar el flujo.

Ejecuta npx libretto help para obtener la lista completa de comandos.

Configuración

Todo el estado de Libretto reside en un directorio .libretto/ en la raíz de tu proyecto. Consulta la documentación de configuración para obtener detalles sobre archivos de configuración, sesiones y perfiles.

Telemetría

Libretto registra telemetría de la CLI para ayudar a comprender el uso de la CLI y priorizar mejoras. Cada comando resuelto puede enviar únicamente un ID de instalación, marca de tiempo, nombre del evento del comando como libretto run, booleano de error, versión del paquete, canal de compilación (node_modules, source o unknown) y, cuando se ha iniciado sesión en Libretto Cloud, el ID de usuario de la nube configurado. Libretto no envía argumentos de comandos, URL, rutas de proyecto, cookies de sesión, claves de API, mensajes de error ni detalles, ni correos electrónicos.

El ID de instalación se almacena en el archivo de telemetría en ~/.libretto/telemetry.json. La implementación reside en packages/libretto/src/cli/core/telemetry.ts.

Para deshabilitar la telemetría, establece LIBRETTO_TELEMETRY_DISABLED=1, establece DO_NOT_TRACK=1, ejecuta con CI=1, o edita ~/.libretto/telemetry.json y establece "enabled": false.

Únete a la comunidad

Únete a nuestro Discord para conectar con otros desarrolladores, obtener ayuda y compartir lo que has construido:

Para hilos más largos, dirígete a Discusiones de GitHub. ¿Encontraste un error? Abre un issue.

Licencia

Licencia MIT — úsalo libremente en proyectos comerciales y de código abierto.

Desarrollo

Para el desarrollo local en este repositorio:

pnpm i
pnpm build
pnpm type-check
pnpm test

Estructura del código fuente:

• packages/libretto/src/cli/ — comandos de la CLI
• packages/libretto/src/runtime/ — runtime del navegador (red, recuperación, descargas)
• packages/libretto/src/shared/ — utilidades compartidas (configuración, cliente LLM, registro, estado)
• packages/libretto/test/ — archivos de prueba (*.spec.ts)
• packages/libretto/README.template.md — fuente de verdad para el repositorio y los READMEs de los paquetes
• packages/libretto/skills/libretto/ — fuente de verdad para la skill de Libretto

Ejecuta pnpm sync:mirrors después de editar packages/libretto/README.template.md o cualquier cosa bajo packages/libretto/skills/libretto/.

Para verificar que los READMEs generados, los espejos de las skills y los metadatos de versión de las skills están sincronizados sin corregirlos, ejecuta pnpm check:mirrors. Para publicar, ejecuta pnpm prepare-release.

[!NOTE] Este es un proyecto en etapa temprana bajo desarrollo activo. Las APIs pueden cambiar antes de la versión 1.0. Recomendamos fijar versiones específicas en producción.

Construido por el equipo de Saffron Health.